@quillmark/svelte 0.18.0 → 0.20.0

package/dist/core/codec/table.d.ts

@@ -25,10 +25,11 @@ export declare function cellAt(props: TableProps, r: number, c: number): TableCe
 /** The table's column count: the one number `header`, every row and `aligns` share. */
 export declare function columnCount(props: TableProps): number;
 /**
- * The rectangularizing constructor: one column count across `header`, every row and
- * `aligns`, padding with empty cells and `none`. The column count is the widest
- * thing present, so a caller that appended to one axis alone still gets a rectangle
- * back, and a table is never narrower than one column.
+ * The rectangularizing constructor: one column count across `header`, every row,
+ * `aligns` and `widths`, padding with empty cells, `none` and auto-fit. The column
+ * count is the widest thing present, so a caller that appended to one axis alone still
+ * gets a rectangle back, and a table is never narrower than one column. The layout
+ * keys ride through, each absent at its default as the store writes it.
  */
 export declare function normalizeTable(props: TableProps): TableProps;
 /**
@@ -58,9 +59,9 @@ export declare function deleteColumn(props: TableProps, c: number): TableProps;
  *  last row. The header travels like any other row, and so does the row that displaces
  *  it: being the header is holding index 0, which a move is free to hand over. */
 export declare function moveRow(props: TableProps, r: number, by: number): TableProps;
-/** Column `c` moved by `by` places, clamped. `aligns` travels with the column: an
- *  alignment is the column's property, so a move that left it behind would retint the
- *  column that took the index. */
+/** Column `c` moved by `by` places, clamped. `aligns` and `widths` travel with the
+ *  column: each is the column's property, so a move that left it behind would retint
+ *  or resize the column that took the index. */
 export declare function moveColumn(props: TableProps, c: number, by: number): TableProps;
 /**
  * Every cell in the inclusive rectangle emptied, alignment kept: what a delete gesture
@@ -68,17 +69,38 @@ export declare function moveColumn(props: TableProps, c: number, by: number): Ta
  * covers ranks and deletes them, and one spanning both is the table itself, so what
  * reaches here is a proper sub-rectangle and the shape it leaves is the shape it found.
  *
- * Alignment is the column's rather than the cells', so it survives a clear that spans one.
+ * A cell keeps its own alignment, and a column its alignment and width: what a clear
+ * empties is text.
  */
 export declare function clearCells(props: TableProps, r0: number, c0: number, r1: number, c1: number): TableProps;
-/** Set column `c`'s alignment: the one table capability the content round-trips
- *  today and nothing in the editor could reach. */
+/** Set column `c`'s alignment: what the held column's cluster and Shift+arrow write
+ *  (`table-view.ts`). */
 export declare function setAlign(props: TableProps, c: number, align: TableAlign): TableProps;
+/** Draw the first row as a header or as a body row: what the header toggle writes
+ *  (`table-view.ts`). */
+export declare function setHeadless(props: TableProps, headless: boolean): TableProps;
+/** A cell's horizontal alignment, and its vertical one: the keys a cell holds beside
+ *  its text, each absent at the default the column or the quill supplies. */
+export type CellAlign = NonNullable<TableCell['align']>;
+export type CellValign = NonNullable<TableCell['valign']>;
+/** Every cell in the inclusive rectangle given `key`'s `value`, or cleared of it where
+ *  `value` is absent, which returns the cell to its column's alignment or the quill's. */
+export declare function setCellLayout<K extends 'align' | 'valign'>(props: TableProps, r0: number, c0: number, r1: number, c1: number, key: K, value: TableCell[K] | undefined): TableProps;
+/** Set or clear the column weights: what a border drag and its double-click write
+ *  (`table-view.ts`). `undefined` returns every column to auto-fit. */
+export declare function setWidths(props: TableProps, widths: (number | null)[] | undefined): TableProps;
 /**
- * A cell as a one-line `Content`: what `decode` takes under the inline schema. The
- * cell's marks are that content's marks, because both are offsets into the same
- * text: the cell-local coordinate space is a `Content`'s coordinate space with
- * one line in it.
+ * Each column's share of the table's width, summing to 1, or `undefined` for a table
+ * that auto-fits throughout. An auto-fit column beside weighted ones takes the mean
+ * weight: the page sizes it to its content, which the editor's grid, laid out fixed so
+ * the weights hold, cannot ask.
+ */
+export declare function columnShares(props: TableProps): number[] | undefined;
+/**
+ * A cell as a one-paragraph `Content`: what `decode` takes under `cellSchema`. Each
+ * `\n` in the text opens a `continues` line, which is the hard break it decodes to and
+ * the one USV `pmToContent` projects a break back to. The cell's marks are that
+ * content's marks, both being offsets into the same text.
  */
 export declare function cellContent(cell: TableCell): Content;
 /**
@@ -98,6 +120,6 @@ export declare function cellFromDoc(doc: PMNode, prior: TableCell): TableCell;
  *  view just produced) from an external one (an undo, a re-hydrate) without a flag.
  *  The marks structurally, for the reason `reconcile.ts` states. */
 export declare function cellEqual(a: TableCell, b: TableCell): boolean;
-/** Whether two tables have the same rectangle and alignment: the change that forces
- *  a rebuild rather than a per-cell reseed. */
+/** Whether two tables have the same rectangle, alignment, header and widths: the
+ *  change that forces a rebuild rather than a per-cell reseed. */
 export declare function shapeEqual(a: TableProps, b: TableProps): boolean;

package/dist/core/codec/table.js

@@ -36,18 +36,23 @@ export function columnCount(props) {
     return props.aligns.length;
 }
 /**
- * The rectangularizing constructor: one column count across `header`, every row and
- * `aligns`, padding with empty cells and `none`. The column count is the widest
- * thing present, so a caller that appended to one axis alone still gets a rectangle
- * back, and a table is never narrower than one column.
+ * The rectangularizing constructor: one column count across `header`, every row,
+ * `aligns` and `widths`, padding with empty cells, `none` and auto-fit. The column
+ * count is the widest thing present, so a caller that appended to one axis alone still
+ * gets a rectangle back, and a table is never narrower than one column. The layout
+ * keys ride through, each absent at its default as the store writes it.
  */
 export function normalizeTable(props) {
     const cols = Math.max(1, props.header.length, props.aligns.length, ...props.rows.map((row) => row.length));
     const fit = (cells) => Array.from({ length: cols }, (_, c) => cells[c] ?? emptyCell());
+    const widths = Array.from({ length: cols }, (_, c) => props.widths?.[c] ?? null);
     return {
         header: fit(props.header),
         rows: props.rows.map(fit),
-        aligns: Array.from({ length: cols }, (_, c) => props.aligns[c] ?? 'none')
+        aligns: Array.from({ length: cols }, (_, c) => props.aligns[c] ?? 'none'),
+        ...(widths.some((w) => w !== null) && { widths }),
+        ...(props.align && { align: props.align }),
+        ...(props.headless && { headless: true })
     };
 }
 /**
@@ -62,9 +67,9 @@ export function allRows(props) {
 /** A flat list back into the stored shape: whatever sits at index 0 is the header, by
  *  position rather than by having been one. No caller passes an empty list — every op
  *  that could reach one refuses the last row first. */
-function fromRows(rows, aligns) {
+function fromRows(props, rows) {
     const [header = [], ...rest] = rows;
-    return normalizeTable({ header, rows: rest, aligns });
+    return normalizeTable({ ...props, header, rows: rest });
 }
 /** A fresh table: a header plus `bodyRows` empty rows, every column unaligned.
  *  Growth is cheap (Tab at the last cell appends a row), so the default is small. */
@@ -79,9 +84,9 @@ export function newTable(cols = 3, bodyRows = 2) {
 export function withCell(props, r, c, cell) {
     const replace = (cells) => cells.map((old, i) => (i === c ? cell : old));
     return normalizeTable({
+        ...props,
         header: r === 0 ? replace(props.header) : props.header,
-        rows: props.rows.map((row, i) => (i === r - 1 ? replace(row) : row)),
-        aligns: props.aligns
+        rows: props.rows.map((row, i) => (i === r - 1 ? replace(row) : row))
     });
 }
 /** A new empty body row below row `r` (row 0, the header, opens the first body row). */
@@ -100,16 +105,18 @@ export function deleteRow(props, r) {
     const rows = allRows(props);
     if (rows.length <= 1 || r < 0 || r >= rows.length)
         return normalizeTable(props);
-    return fromRows(rows.filter((_, i) => i !== r), props.aligns);
+    return fromRows(props, rows.filter((_, i) => i !== r));
 }
 /** A new empty column after column `c`. */
 export function insertColumn(props, c) {
     const at = Math.max(0, Math.min(c + 1, columnCount(props)));
-    const splice = (cells) => [...cells.slice(0, at), emptyCell(), ...cells.slice(at)];
+    const splice = (xs, fresh) => [...xs.slice(0, at), fresh, ...xs.slice(at)];
     return normalizeTable({
-        header: splice(props.header),
-        rows: props.rows.map(splice),
-        aligns: [...props.aligns.slice(0, at), 'none', ...props.aligns.slice(at)]
+        ...props,
+        header: splice(props.header, emptyCell()),
+        rows: props.rows.map((row) => splice(row, emptyCell())),
+        aligns: splice(props.aligns, 'none'),
+        widths: props.widths && splice(props.widths, null)
     });
 }
 /** Drop column `c`; a no-op at one column (a table has at least one). */
@@ -118,9 +125,11 @@ export function deleteColumn(props, c) {
         return normalizeTable(props);
     const drop = (xs) => xs.filter((_, i) => i !== c);
     return normalizeTable({
+        ...props,
         header: drop(props.header),
         rows: props.rows.map(drop),
-        aligns: drop(props.aligns)
+        aligns: drop(props.aligns),
+        widths: props.widths && drop(props.widths)
     });
 }
 /** One element moved within an array, out of place. The whole of what both move ops
@@ -140,20 +149,22 @@ export function moveRow(props, r, by) {
     const to = Math.max(0, Math.min(r + by, rows.length - 1));
     if (r === to || r < 0 || r >= rows.length)
         return normalizeTable(props);
-    return fromRows(move(rows, r, to), props.aligns);
+    return fromRows(props, move(rows, r, to));
 }
-/** Column `c` moved by `by` places, clamped. `aligns` travels with the column: an
- *  alignment is the column's property, so a move that left it behind would retint the
- *  column that took the index. */
+/** Column `c` moved by `by` places, clamped. `aligns` and `widths` travel with the
+ *  column: each is the column's property, so a move that left it behind would retint
+ *  or resize the column that took the index. */
 export function moveColumn(props, c, by) {
     const to = Math.max(0, Math.min(c + by, columnCount(props) - 1));
     if (c === to || c < 0 || c >= columnCount(props))
         return normalizeTable(props);
     const shift = (xs) => move(xs, c, to);
     return normalizeTable({
+        ...props,
         header: shift(props.header),
         rows: props.rows.map(shift),
-        aligns: shift(props.aligns)
+        aligns: shift(props.aligns),
+        widths: props.widths && shift(props.widths)
     });
 }
 /**
@@ -162,35 +173,86 @@ export function moveColumn(props, c, by) {
  * covers ranks and deletes them, and one spanning both is the table itself, so what
  * reaches here is a proper sub-rectangle and the shape it leaves is the shape it found.
  *
- * Alignment is the column's rather than the cells', so it survives a clear that spans one.
+ * A cell keeps its own alignment, and a column its alignment and width: what a clear
+ * empties is text.
  */
 export function clearCells(props, r0, c0, r1, c1) {
-    const blank = (cells, r) => cells.map((cell, c) => (r >= r0 && r <= r1 && c >= c0 && c <= c1 ? emptyCell() : cell));
+    const blank = (cells, r) => cells.map((cell, c) => r >= r0 && r <= r1 && c >= c0 && c <= c1 ? { ...cell, text: '', marks: [] } : cell);
     return normalizeTable({
+        ...props,
         header: blank(props.header, 0),
-        rows: props.rows.map((row, i) => blank(row, i + 1)),
-        aligns: props.aligns
+        rows: props.rows.map((row, i) => blank(row, i + 1))
     });
 }
-/** Set column `c`'s alignment: the one table capability the content round-trips
- *  today and nothing in the editor could reach. */
+/** Set column `c`'s alignment: what the held column's cluster and Shift+arrow write
+ *  (`table-view.ts`). */
 export function setAlign(props, c, align) {
     return normalizeTable({
         ...props,
         aligns: props.aligns.map((a, i) => (i === c ? align : a))
     });
 }
+/** Draw the first row as a header or as a body row: what the header toggle writes
+ *  (`table-view.ts`). */
+export function setHeadless(props, headless) {
+    return normalizeTable({ ...props, headless: headless || undefined });
+}
+/** Every cell in the inclusive rectangle given `key`'s `value`, or cleared of it where
+ *  `value` is absent, which returns the cell to its column's alignment or the quill's. */
+export function setCellLayout(props, r0, c0, r1, c1, key, value) {
+    const lay = (cells, r) => cells.map((cell, c) => {
+        if (r < r0 || r > r1 || c < c0 || c > c1)
+            return cell;
+        const next = { ...cell, [key]: value };
+        if (value === undefined)
+            delete next[key];
+        return next;
+    });
+    return normalizeTable({
+        ...props,
+        header: lay(props.header, 0),
+        rows: props.rows.map((row, i) => lay(row, i + 1))
+    });
+}
+/** Set or clear the column weights: what a border drag and its double-click write
+ *  (`table-view.ts`). `undefined` returns every column to auto-fit. */
+export function setWidths(props, widths) {
+    return normalizeTable({ ...props, widths });
+}
+/**
+ * Each column's share of the table's width, summing to 1, or `undefined` for a table
+ * that auto-fits throughout. An auto-fit column beside weighted ones takes the mean
+ * weight: the page sizes it to its content, which the editor's grid, laid out fixed so
+ * the weights hold, cannot ask.
+ */
+export function columnShares(props) {
+    const set = props.widths?.filter((w) => w !== null);
+    if (!props.widths || !set?.length)
+        return undefined;
+    const mean = set.reduce((a, b) => a + b, 0) / set.length;
+    const weights = props.widths.map((w) => w ?? mean);
+    const total = weights.reduce((a, b) => a + b, 0);
+    return weights.map((w) => w / total);
+}
 // ── The cell codec ──────────────────────────────────────────────────────────
 /**
- * A cell as a one-line `Content`: what `decode` takes under the inline schema. The
- * cell's marks are that content's marks, because both are offsets into the same
- * text: the cell-local coordinate space is a `Content`'s coordinate space with
- * one line in it.
+ * A cell as a one-paragraph `Content`: what `decode` takes under `cellSchema`. Each
+ * `\n` in the text opens a `continues` line, which is the hard break it decodes to and
+ * the one USV `pmToContent` projects a break back to. The cell's marks are that
+ * content's marks, both being offsets into the same text.
  */
 export function cellContent(cell) {
+    const breaks = cell.text.split('\n').length - 1;
     return {
         text: cell.text,
-        lines: [{ containers: [], kind: 'para' }],
+        lines: [
+            { containers: [], kind: 'para' },
+            ...Array.from({ length: breaks }, () => ({
+                containers: [],
+                kind: 'para',
+                continues: true
+            }))
+        ],
         marks: cell.marks,
         islands: []
     };
@@ -210,29 +272,38 @@ export function cellContent(cell) {
 export function cellFromDoc(doc, prior) {
     const projected = pmToContent(doc);
     const text = projected.text;
+    const layout = cellLayout(prior);
     const anchors = prior.marks.filter((m) => m.type === 'anchor');
     if (!anchors.length)
-        return { text, marks: projected.marks };
+        return { ...layout, text, marks: projected.marks };
     const before = cellContent(prior);
     const delta = contentEdit(before, cellContent({ text, marks: [] })).delta;
     const rebased = core()
         .mapMarks(before, delta ? { delta } : {})
         .filter((m) => m.type === 'anchor');
     return {
+        ...layout,
         text,
         marks: [...projected.marks, ...rebased].sort((a, b) => a.start - b.start || a.end - b.end)
     };
 }
+/** A cell's keys beside its text and marks: what no edit of the text touches. */
+function cellLayout(cell) {
+    const { text: _text, marks: _marks, ...layout } = cell;
+    return layout;
+}
 /** Whether two cells are the same value: what tells an own edit (the projection the
  *  view just produced) from an external one (an undo, a re-hydrate) without a flag.
  *  The marks structurally, for the reason `reconcile.ts` states. */
 export function cellEqual(a, b) {
     return a.text === b.text && valueEqual(a.marks, b.marks);
 }
-/** Whether two tables have the same rectangle and alignment: the change that forces
- *  a rebuild rather than a per-cell reseed. */
+/** Whether two tables have the same rectangle, alignment, header and widths: the
+ *  change that forces a rebuild rather than a per-cell reseed. */
 export function shapeEqual(a, b) {
     return (a.rows.length === b.rows.length &&
         a.aligns.length === b.aligns.length &&
-        a.aligns.every((x, i) => x === b.aligns[i]));
+        a.aligns.every((x, i) => x === b.aligns[i]) &&
+        !a.headless === !b.headless &&
+        valueEqual(a.widths, b.widths));
 }

package/dist/core/theme.css

@@ -235,7 +235,7 @@
 	   Offset-free is the whole of it: an offset states where the light is and no pole
 	   carries that, where a halo states occlusion. Toward black at both poles for the
 	   same reason — a crevice is darker than what surrounds it in a dark room too — so
-	   the cue means one thing whichever way the scale runs. Spent only on what portals,
+	   the cue means one thing whichever way the scale runs. Spent only on what floats,
 	   and the one shadow any surface casts, which is review's to hold. */
 	--_qm-lift: 0 0 12px color-mix(in oklab, #000 16%, transparent);
 	/* The recede ladder: a hover-revealed or disabled affordance at rest, and a

package/dist/visual/ArrayField.svelte

@@ -76,6 +76,7 @@
 		type ArrayLayout
 	} from './structure.js';
 	import { splitDeep, unrouted, type DeepDiagnostic } from './diagnostics.js';
+	import { propertyDomIds } from './domid.js';
 	import type { LandingBox } from './leaves.js';
 	import { reorder, reorderArm } from './motion.js';
 	import Icon from './icons/Icon.svelte';
@@ -91,7 +92,7 @@
 	const CHEVRON = 16;
 
 	interface Props {
-		value: unknown[] | undefined;
+		value: unknown;
 		/** The declared `default:`: the rows an unset array draws, which a gesture takes. */
 		fallback?: unknown[];
 		items: QuillFieldSchema | undefined;
@@ -156,11 +157,18 @@
 	const table = $derived(layout === 'table' && control === 'object');
 	const columns = $derived(Object.entries(items?.properties ?? {}));
 	const defaulted = $derived(value == null && (fallback?.length ?? 0) > 0);
-	const arr = $derived((value ?? fallback ?? []) as unknown[]);
-	/** The rows' content read: the boundary's, or, while the rows are the default, the
-	 *  literal's own leaf at the codec its declared type names. */
+	// A bare value is the one-element list the render floor wraps it into (canon
+	// `SCHEMAS.md` §"Type coercion"), and the reader answers no element of it.
+	const bare = $derived(value != null && !Array.isArray(value));
+	const arr = $derived(rowsOf(value));
+	function rowsOf(v: unknown): unknown[] {
+		if (v == null) return fallback ?? [];
+		return Array.isArray(v) ? v : [v];
+	}
+	/** The rows' content read: the boundary's, or, while the rows are the default or a
+	 *  bare value, the literal's own leaf at the codec its declared type names. */
 	function readAt(path: PathStep[]): Content | undefined {
-		if (!defaulted) return contentAt(path);
+		if (!defaulted && !bare) return contentAt(path);
 		const leaf = schemaAt({ type: 'array', items }, path);
 		let v: unknown = arr;
 		for (const step of path) v = (v as Record<string | number, unknown> | undefined)?.[step];
@@ -177,7 +185,7 @@
 	// an effect-only seed mounts every element editor in a second render.
 	const seq = new IdSeq();
 	// svelte-ignore state_referenced_locally
-	let ids = $state<string[]>(seq.take((value ?? fallback ?? []).length));
+	let ids = $state<string[]>(seq.take(rowsOf(value).length));
 	// Length reconcile (defend against an out-of-band length change);
 	// order is maintained by the mutators, not here.
 	$effect(() => {
@@ -593,6 +601,7 @@
 						>
 							<FieldLabel
 								label={columnTitle(key, sub)}
+								descriptionId={idBase != null ? propertyDomIds(idBase, key).description : undefined}
 								required={obliged(sub)}
 								description={sub.description}
 							/>
@@ -605,6 +614,7 @@
 						<ObjectField
 							bare
 							bind:this={cellEls[id]}
+							{idBase}
 							value={(arr[k] ?? {}) as Record<string, unknown>}
 							properties={items?.properties}
 							label={rowName(k)}
@@ -690,6 +700,7 @@
 						<ProseValue
 							bind:this={els[id]}
 							content={() => readAt([k])}
+							value={arr[k]}
 							plaintext={items != null && baseType(items) === 'plaintext'}
 							label={rowName(k)}
 							onChange={(rt) => commitElement(k, rt)}

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

@@ -3,7 +3,7 @@ import { type ArrayLayout } from './structure.js';
 import { type DeepDiagnostic } from './diagnostics.js';
 import type { LandingBox } from './leaves.js';
 interface Props {
-    value: unknown[] | undefined;
+    value: unknown;
     /** The declared `default:`: the rows an unset array draws, which a gesture takes. */
     fallback?: unknown[];
     items: QuillFieldSchema | undefined;

package/dist/visual/Field.svelte

@@ -27,7 +27,7 @@
 		ResolvedField
 	} from '@quillmark/wasm';
 	import type { EditorErrorHandler } from '../core/errors.js';
-	import type { LandingBox, LeafRegistry } from './leaves.js';
+	import { seatValueLeaves, type LandingBox, type LeafRegistry } from './leaves.js';
 	import type { FieldModel, FieldSpan } from './structure.js';
 	import {
 		VARIANT_DISCRIMINANT,
@@ -250,6 +250,13 @@
 		return () => registry.unregisterControl(key);
 	}
 
+	// A by-value prose leaf anywhere inside this field's containers is reached under
+	// this field's key: the active address names the field, never the element or cell.
+	seatValueLeaves({
+		focus: (leaf) => leaves?.focusValue(leafKey, leaf),
+		release: (leaf) => leaves?.releaseValue(leafKey, leaf)
+	});
+
 	/**
 	 * A form control has no controller to report its focus through, so the wrapper
 	 * reports: `focusin` bubbles, so one handler covers a plain input, an array's N
@@ -361,7 +368,7 @@
 			{:else if field.control === 'array'}
 				<ArrayField
 					bind:this={arrayEl}
-					value={value as unknown[] | undefined}
+					{value}
 					fallback={Array.isArray(field.schema.default) ? field.schema.default : undefined}
 					items={field.schema.items}
 					layout={arrayLayout(field.schema)}
@@ -400,7 +407,6 @@
 					labelId={domIds.label}
 					descriptionId={domIds.description}
 					idBase={domIds.control}
-					listKey={leafKey}
 					{contentAt}
 					onCommit={onCommitScalar}
 					diagnostics={deep}

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

@@ -1,6 +1,6 @@
 import type { Document, Quill, Addr, Diagnostic, ResolvedField } from '@quillmark/wasm';
 import type { EditorErrorHandler } from '../core/errors.js';
-import type { LeafRegistry } from './leaves.js';
+import { type LeafRegistry } from './leaves.js';
 import type { FieldModel, FieldSpan } from './structure.js';
 import type { FieldDomIds } from './domid.js';
 interface Props {

package/dist/visual/FieldHint.svelte

@@ -20,9 +20,13 @@
  {@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.
+ Three ways in, one per input modality: hover (pointer), tap (touch), and an
+ activation with no pointer behind it (keyboard), wired here rather than taken from
+ `Tooltip`, whose trigger returns early on `pointerType === 'touch'` and closes on
+ click. The keyboard's activation is `Mod-/` on the control the description describes
+ (`guidance.ts`), not a stop on this glyph: a stop here would double every described
+ field's Tab stops, so the glyph is out of the tab order. A screen reader activating
+ it lands on the same toggle.
 -->
 <script lang="ts">
 	import { Popover } from 'bits-ui';
@@ -81,10 +85,51 @@
 		return lines === 1;
 	}
 
-	function raise(): void {
+	/** How far the trigger's target reaches past its glyph on the axis the surface stands
+	 * on, which makes the side offset clearance from the target rather than from the
+	 * glyph. The target is `.qm-tap-floor`'s box (controls.css), centred on the glyph and
+	 * read off it rather than restated. A surface landing on the target takes a resting
+	 * pointer off the trigger, which closes the surface, and hands the pointer back as it
+	 * goes: a loop. A DOM with no layout reads none. */
+	let reach = $state(0);
+
+	function targetReach(): number {
+		if (triggerEl === undefined) return 0;
+		const glyph = triggerEl.getBoundingClientRect();
+		const target = getComputedStyle(triggerEl, '::after');
+		const [across, own] = beside ? [target.width, glyph.width] : [target.height, glyph.height];
+		return Math.max(0, (parseFloat(across) - own) / 2) || 0;
+	}
+
+	/** What a keyboard raise was asked from: the described control, holding focus while
+	 * the trigger never does, so its leaving and its Escape are what lower the surface. */
+	let from = $state<HTMLElement | undefined>(undefined);
+
+	function raise(origin?: HTMLElement): void {
+		from = origin;
 		beside = ridesTheRung();
+		reach = targetReach();
 		open = true;
 	}
+
+	$effect(() => {
+		if (!open || !from) return;
+		const owner = from;
+		const leave = (e: FocusEvent) => {
+			if (!(e.relatedTarget instanceof Node && owner.contains(e.relatedTarget))) open = false;
+		};
+		const escape = (e: KeyboardEvent) => {
+			if (e.key !== 'Escape' || e.defaultPrevented) return;
+			e.stopPropagation();
+			open = false;
+		};
+		owner.addEventListener('focusout', leave);
+		owner.addEventListener('keydown', escape);
+		return () => {
+			owner.removeEventListener('focusout', leave);
+			owner.removeEventListener('keydown', escape);
+		};
+	});
 </script>
 
 <!-- The trigger is ours, not `Popover.Trigger`, and the surface anchors to it:
@@ -96,6 +141,7 @@
 	bind:this={triggerEl}
 	type="button"
 	class="qm-field-hint qm-icon-btn qm-focus-ring qm-tap-floor"
+	tabindex="-1"
 	aria-label="{label} guidance"
 	aria-expanded={open}
 	aria-describedby={describedBy}
@@ -114,11 +160,17 @@
 			else raise();
 		}
 	}}
-	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')) raise();
+	onclick={(e) => {
+		// No pointer behind it (`detail` 0): the guidance key or a screen reader. A
+		// mouse click falls through to hover and a tap to `pointerup`, as above. The
+		// owner is whatever holds focus and is described by this trigger's node.
+		if (e.detail !== 0) return;
+		if (open) open = false;
+		else
+			raise(
+				document.activeElement?.closest<HTMLElement>(`[aria-describedby~="${describedBy}"]`) ??
+					undefined
+			);
 	}}
 	onblur={() => (open = false)}
 	onkeydown={(e) => {
@@ -153,7 +205,7 @@
 			collisionBoundary={bounds}
 			side={beside ? 'right' : 'top'}
 			align={beside ? 'center' : 'start'}
-			sideOffset={6}
+			sideOffset={6 + reach}
 			trapFocus={false}
 			onOpenAutoFocus={(e: Event) => e.preventDefault()}
 			onCloseAutoFocus={(e: Event) => e.preventDefault()}