@quillmark/svelte 0.18.0 → 0.20.0

package/dist/visual/ProseValue.svelte

@@ -11,24 +11,35 @@
  Mounts once per stable key (an element's session id, a property's name), so the
  parent's re-derive leaves the caret where it is.
 
+ Having no address, it registers no controller: it announces its views into the
+ registry's by-value lane under the field it stands in (`leaves.ts`), the formatting
+ popover's door to it. A focus on an editable leaf announces them, and so does a write
+ releasing the leaf under the caret; a hold and an unmount withdraw them, and a blur
+ does not, the popover's link prompt taking the focus from the view it writes to.
+
  The content is read, not passed: `reader.getContentAt(addr, path)` decodes through
  the codec the leaf's own declared type names, so what it rests as — the content
  object, a `plaintext` literal, the authored string a transport door left — stops
- being the row's or the cell's business. Read once, at mount, since that is when this
- leaf takes its state.
+ being the row's or the cell's business. It is read at mount and again wherever the
+ parent's re-derive hands down a `value` that moved, and a read differing from the
+ content the leaf last committed or took replaces the view, the gate `createField`
+ re-hydrates through (`reconcile.ts`): a write that lands in the store under a mounted
+ leaf is what its next keystroke edits. Its own commit is read back as the store took
+ it, so the echo replaces nothing and the caret and the history stay.
 
  The schema is the declared type's where the parent has room for it: a subform cell
  declaring no `inline` takes the full row ({@link ObjectField}), a `richtext` one on the
  block schema and a `plaintext` one on the plain schema, paragraphs and hard breaks.
  An array element is one textblock whatever it declares, since Enter there is the
- repeater's. There is no slash menu at either width, and an island draws as its
- placeholder: an atom a keystroke can delete and no view edits.
+ repeater's. There is no slash menu at either width, and no island view.
 
- A leaf over content its schema cannot hold is held: a narrowed one over anything but
- one plain paragraph (`fitsInline`), a plain one over anything but plain lines
- (`fitsPlain`). Its decode would join or drop what is left over, and the first
- keystroke would write that loss back, so a held leaf draws its content on the block
- schema, read-only, with a note inside its box, and commits nothing.
+ A leaf over content it cannot edit is held (`fitsLeaf`): a narrowed one over anything
+ but one plain paragraph, a plain one over anything but plain lines, where the decode
+ would join or drop what is left over for the first keystroke to write back, and a block
+ one over an island, which draws as its placeholder tag, an atom a keystroke deletes
+ unseen. A held leaf draws its content on the block schema, read-only, with a note
+ inside its box, and commits nothing. The hold is judged of what each mount and each
+ replacement reads, so a write moving the value takes it or releases it.
 -->
 <script lang="ts">
 	import { untrack } from 'svelte';
@@ -36,6 +47,7 @@
 	import { EditorView } from 'prosemirror-view';
 	import {
 		blockSchema,
+		createReconciler,
 		decode,
 		emptyContent,
 		fitsLeaf,
@@ -45,18 +57,26 @@
 		proseAttributes,
 		proseLeafPlugins,
 		buildLineIndex,
-		usvToPM
+		pmToUsv,
+		usvToPM,
+		valueEqual,
+		type LeafViews
 	} from '../core/codec/index.js';
+	import { valueLeafSeat } from './leaves.js';
 	import { wording } from './strings.js';
 	import './controls.css';
 	import type { Content } from '@quillmark/wasm';
 
 	interface Props {
-		/** This leaf's content, read at mount (the parent's boundary read), `undefined`
-		 * where nothing is stored. A thunk rather than a value: the parent re-derives
-		 * per revision and this leaf takes its state once, so a value prop would be a
-		 * boundary read per leaf per render, all but one of them discarded. */
+		/** This leaf's content (the parent's boundary read), `undefined` where nothing is
+		 * stored: read at mount and wherever {@link value} moves. A thunk rather than a
+		 * value: the parent re-derives per revision, and a value prop would be a
+		 * boundary read per leaf per render, all but the moved one discarded. */
 		content: () => Content | undefined;
+		/** This leaf's value as the parent's re-derive delivers it, stored form and all:
+		 * compared with the last one delivered, never drawn, so a move is what re-reads
+		 * {@link content}. */
+		value?: unknown;
 		/** The default an unset leaf holds, where it prints: drawn at the default rung,
 		 * and handed up whole with the first edit in it, as `createField` takes one. */
 		fallback?: Content;
@@ -87,6 +107,7 @@
 	}
 	let {
 		content,
+		value,
 		fallback,
 		plaintext = false,
 		block = false,
@@ -99,10 +120,13 @@
 	}: Props = $props();
 
 	const t = wording();
+	const seat = valueLeafSeat();
 	const uid = $props.id();
 	const heldId = `${uid}-held`;
 	let held = $state(false);
 	let view: EditorView | undefined;
+	/** What the mounted view does with a value the parent's re-derive delivers. */
+	let follow: ((next: unknown) => void) | undefined;
 	/** Take the caret: what a parent placing focus on this leaf calls. The view's
 	 * focus, not the element's: a PM view restores its selection, where a bare DOM
 	 * focus on a contenteditable leaves the caret unplaced. And the reveal beside it,
@@ -135,46 +159,61 @@
 
 	function mountView(mount: HTMLDivElement): () => void {
 		return untrack(() => {
-			// The same keymap and plugin stack a `createField` leaf mounts (shared
-			// `proseLeafPlugins`), minus the anchor-position plugin: anchors are dropped on
-			// the parent's value write, per the header.
 			const inline = !block;
+			const leaf = { inline, plaintext, islands: false };
+			const names = { label, labelledBy, describedBy };
+			const shown = (stored: Content | undefined): Content => stored ?? fallback ?? emptyContent();
 			const stored = content();
-			const rt = stored ?? fallback ?? emptyContent();
+			let seen = value;
 			let defaulted = stored === undefined && !!fallback;
-			held = !fitsLeaf(rt, { inline, plaintext });
-			const named = held
-				? heldAttributes({ label, labelledBy, describedBy }, heldId)
-				: (proseAttributes({ label, labelledBy, describedBy }) ?? {});
-			const defaultNamed = { ...named, 'data-default': '' };
-			const schema = held ? blockSchema : leafSchema({ plaintext, inline });
-			const state = EditorState.create({
-				doc: decode(rt, schema),
-				plugins: held
-					? []
-					: proseLeafPlugins(schema, {
-							inline,
-							placeholder: () => placeholder,
-							placeholderUntilEdit: true
-						})
-			});
+			const reconciler = createReconciler(shown(stored));
+			held = !fitsLeaf(reconciler.last, leaf);
+			// Which of `aria-label` / `aria-labelledby` wins is the codec's one answer
+			// (`proseAttributes`), so a cell carrying a label element and a row carrying
+			// none cannot name their regions by different rules.
+			const plainNamed = proseAttributes(names) ?? {};
+			const heldNamed = heldAttributes(names, heldId);
+			const build = (rt: Content): EditorState => {
+				// The same keymap and plugin stack a `createField` leaf mounts (shared
+				// `proseLeafPlugins`), minus the anchor-position plugin: anchors are dropped on
+				// the parent's value write, per the header.
+				const schema = held ? blockSchema : leafSchema({ plaintext, inline });
+				return EditorState.create({
+					doc: decode(rt, schema),
+					plugins: held
+						? []
+						: proseLeafPlugins(schema, {
+								inline,
+								placeholder: () => placeholder,
+								placeholderUntilEdit: true
+							})
+				});
+			};
 			const mounted = new EditorView(
 				{ mount },
 				{
-					state,
+					state: build(reconciler.last),
 					editable: () => !held,
-					// Which of `aria-label` / `aria-labelledby` wins is the codec's one answer
-					// (`proseAttributes`), so a cell carrying a label element and a row carrying
-					// none cannot name their regions by different rules.
-					attributes: () => (defaulted ? defaultNamed : named),
+					attributes: () => {
+						const named = held ? heldNamed : plainNamed;
+						return defaulted ? { ...named, 'data-default': '' } : named;
+					},
 					dispatchTransaction(tr) {
 						const next = mounted.state.apply(tr);
 						const edit = tr.docChanged && !held;
 						if (edit) defaulted = false;
 						mounted.updateState(next);
-						if (edit) onChange(pmToContent(next.doc));
+						if (!edit) return;
+						onChange(pmToContent(next.doc));
+						// The commit as the store took it, so its echo through the re-derive is no move.
+						seen = value;
+						reconciler.commit(shown(content()));
 					},
 					handleDOMEvents: {
+						focus: () => {
+							if (!held) seat?.focus(views);
+							return false;
+						},
 						keydown: (_v, e) => {
 							onKey?.(e);
 							return false;
@@ -182,13 +221,47 @@
 					}
 				}
 			);
+			const views: LeafViews = {
+				view: mounted,
+				focusedView: () => mounted,
+				nestedViews: () => []
+			};
 			view = mounted;
+			follow = (next) => {
+				if (valueEqual(next, seen)) return;
+				seen = next;
+				const read = content();
+				const current = shown(read);
+				const holds = !fitsLeaf(current, leaf);
+				const wasDefaulted = defaulted;
+				defaulted = read === undefined && !!fallback;
+				if (holds === held && !reconciler.shouldRehydrate(current)) {
+					if (defaulted !== wasDefaulted) mounted.setProps({});
+					return;
+				}
+				held = holds;
+				if (held) seat?.release(views);
+				else if (mounted.hasFocus()) seat?.focus(views);
+				// The caret keeps its offset, clamped, as a field's re-hydrate keeps it.
+				const caret = pmToUsv(buildLineIndex(mounted.state.doc), mounted.state.selection.head);
+				const fresh = build(current);
+				const sel = Selection.near(fresh.doc.resolve(usvToPM(buildLineIndex(fresh.doc), caret)));
+				mounted.updateState(fresh.apply(fresh.tr.setSelection(sel)));
+				reconciler.commit(current);
+			};
 			return () => {
+				seat?.release(views);
+				follow = undefined;
 				view = undefined;
 				mounted.destroy();
 			};
 		});
 	}
+
+	$effect(() => {
+		const next = value;
+		untrack(() => follow?.(next));
+	});
 </script>
 
 <!-- `.qm-control-box` (controls.css) is the whole box, so an array of `richtext` and

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

@@ -1,10 +1,14 @@
 import type { Content } from '@quillmark/wasm';
 interface Props {
-    /** This leaf's content, read at mount (the parent's boundary read), `undefined`
-     * where nothing is stored. A thunk rather than a value: the parent re-derives
-     * per revision and this leaf takes its state once, so a value prop would be a
-     * boundary read per leaf per render, all but one of them discarded. */
+    /** This leaf's content (the parent's boundary read), `undefined` where nothing is
+     * stored: read at mount and wherever {@link value} moves. A thunk rather than a
+     * value: the parent re-derives per revision, and a value prop would be a
+     * boundary read per leaf per render, all but the moved one discarded. */
     content: () => Content | undefined;
+    /** This leaf's value as the parent's re-derive delivers it, stored form and all:
+     * compared with the last one delivered, never drawn, so a move is what re-reads
+     * {@link content}. */
+    value?: unknown;
     /** The default an unset leaf holds, where it prints: drawn at the default rung,
      * and handed up whole with the first edit in it, as `createField` takes one. */
     fallback?: Content;

package/dist/visual/VisualEditorInner.svelte

@@ -46,7 +46,7 @@
 	import type { VisualEditorProps } from './props.js';
 	import { mergeStrings, setWording } from './strings.js';
 	import type { CardId, ChangeSource } from './signals.js';
-	import type { FieldController } from '../core/codec/index.js';
+	import type { FieldController, LeafViews } from '../core/codec/index.js';
 	import {
 		IdSeq,
 		controlKind,
@@ -79,11 +79,11 @@
 		type RoutedDiagnostic
 	} from './diagnostics.js';
 	import { fieldDomIds, groupPanelId } from './domid.js';
-	import { createLeafRegistry, type FieldControl } from './leaves.js';
+	import { createLeafRegistry, type ActiveProse, type FieldControl } from './leaves.js';
 	import { reorder, reorderArm, reorderTrips } from './motion.js';
 	import { tipsChannel } from './tips.js';
-	import { cardChecklists, setChecklists } from './checklists.js';
 	import { patchEditorExt } from './ext.js';
+	import { raiseGuidance } from './guidance.js';
 	import Card from './Card.svelte';
 	import TipsCard from './TipsCard.svelte';
 	import FormatPopover from './FormatPopover.svelte';
@@ -654,20 +654,6 @@
 		};
 	});
 
-	// The document's checklists, which an open matrix's add box searches whole
-	// (`checklists.ts`): off the model, so a list in a closed group or another card is
-	// reached without being mounted.
-	const lists = $derived(
-		cardChecklists(
-			[model.main, ...model.cards],
-			(c) => c.titleOverride || c.titlePlaceholder,
-			(c, field) => pathFor(makeAddr(c.id, c.isMain, field)),
-			(c, field) => fieldKeyToString({ card: c.isMain ? undefined : c.id, field }),
-			(c, field, next) => commitScalar(c.id, c.isMain, field, next)
-		)
-	);
-	setChecklists({ list: () => lists, land: (path) => void focusField(path) });
-
 	// ── Public entry points ─────────────────────────────────────────────────────
 	/**
 	 * Resolve a preview {@link Landing} to a mounted leaf and land in it.
@@ -694,12 +680,18 @@
 		const box = await land(found, at.granularity === 'segment' ? undefined : at.pos);
 		if (span.alive) bloomInside(box);
 	}
-	/** The active leaf's controller: the formatting popover's observation seam.
-	 *  `undefined` for a focused form control, which holds no marks to toggle. */
-	export function getActiveLeaf(): FieldController | undefined {
+	/** The active prose leaf: the formatting popover's observation seam. The active
+	 *  field's controller where it registered one, else the by-value leaf focused last
+	 *  under it (`leaves.ts`); `undefined` for a form control, which holds no marks to
+	 *  toggle. */
+	export function getActiveLeaf(): ActiveProse | undefined {
 		if (!activeAddr) return undefined;
 		const card = activeAddr.card != null ? activeCardId : undefined;
-		return leaves.prose(fieldKeyToString({ card, field: activeAddr.field }));
+		const key = fieldKeyToString({ card, field: activeAddr.field });
+		const controller = leaves.prose(key);
+		if (controller) return { views: controller as FieldController & LeafViews, controller };
+		const views = leaves.value(key);
+		return views && { views };
 	}
 
 	/**
@@ -856,7 +848,15 @@
 	}
 </script>
 
-<div class="qm-editor {className ?? ''}" {style} data-qm-root bind:this={rootEl}>
+<!-- The keydown is a control's, bubbled: the root resolves which description it raises. -->
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div
+	class="qm-editor {className ?? ''}"
+	{style}
+	data-qm-root
+	bind:this={rootEl}
+	onkeydown={raiseGuidance}
+>
 	<!-- `main` and the tips card are one block in the stack: the tips card tucks under
 	 `main`'s bottom corners, so the two share a seam rather than a gutter and the
 	 wrapper is what holds them to it. -->

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

@@ -1,10 +1,10 @@
 import { type DocPath, type Landing } from '../core/address.js';
 import type { VisualEditorProps } from './props.js';
 import type { CardId } from './signals.js';
-import type { FieldController } from '../core/codec/index.js';
+import { type ActiveProse } from './leaves.js';
 declare const VisualEditorInner: import("svelte").Component<VisualEditorProps, {
     setCaret: (at: Landing) => Promise<void>;
-    getActiveLeaf: () => FieldController | undefined;
+    getActiveLeaf: () => ActiveProse | undefined;
     focusField: (field: DocPath) => Promise<void>;
     insertCard: (kind: string, at?: number) => CardId | undefined;
     removeCard: (cardId: CardId) => void;

package/dist/visual/checklists.d.ts

@@ -1,82 +1,3 @@
 import type { QuillFieldSchema } from '@quillmark/wasm';
-import type { DocPath } from '../core/address.js';
-import { type CardModel, type MatrixMember } from './structure.js';
-/** One matrix of the document, as the add box reaches it. */
-export interface Checklist {
-    /** The field's leaf key: how a mounted matrix tells itself from the rest. */
-    key: string;
-    /** The field's path, the prefix a member's landing address extends. */
-    path: DocPath;
-    /** What a result from this list reads under: the field's label, and the card's
-     *  where the field is not the main card's. */
-    label: string;
-    schema: QuillFieldSchema;
-    /** The held set as it prints: the stored map, else the declared `default:`. */
-    value: Record<string, unknown> | undefined;
-    /** Commit the whole map, as the field's own control does. */
-    commit: (next: Record<string, unknown> | undefined) => void;
-}
-export interface ChecklistIndex {
-    list: () => readonly Checklist[];
-    /** Reveal and focus a member by its address. */
-    land: (path: DocPath) => void;
-}
-export declare function setChecklists(index: ChecklistIndex): void;
-/** The index under a mounted editor; `undefined` off-tree. */
-export declare function checklists(): ChecklistIndex | undefined;
 /** The value a matrix prints: the stored map, else a mapping `default:`. */
 export declare function matrixPrinted(value: unknown, schema: QuillFieldSchema): Record<string, unknown> | undefined;
-/** Every card-level matrix of the cards, in document order. */
-export declare function cardChecklists(cards: readonly CardModel[], cardLabel: (card: CardModel) => string, path: (card: CardModel, field: string) => DocPath | undefined, leafKey: (card: CardModel, field: string) => string, commit: (card: CardModel, field: string, next: Record<string, unknown> | undefined) => void): Checklist[];
-/** Every item a matrix can show: the roster in declaration order, then the items its
- *  map adds, in id order. */
-export declare function checklistItems(schema: QuillFieldSchema, value: Record<string, unknown> | undefined): MatrixMember[];
-/** One option of an add box. */
-export interface AddOption {
-    /** Stable across one query's options: the option element's id suffix. */
-    key: string;
-    title: string;
-    /** Words after the title: the list a result stands in, its held state. */
-    note?: string;
-    /** The option that adds what was typed, rather than a result. */
-    add?: boolean;
-    /** A result the typed words name outright, which Enter takes unarrowed: an add box
-     *  whose best result is weaker takes its add option instead. */
-    strong?: boolean;
-    /** What the owner reads back off a chosen option. */
-    payload?: unknown;
-}
-/** One search result: an item of some checklist, `list` naming which. */
-export interface ChecklistHit<L> {
-    list: L;
-    id: string;
-    title: string;
-    held: boolean;
-    score: number;
-    /** Every query word claimed a title word whole or as its opening. */
-    strong: boolean;
-}
-/**
- * How well `query` names `title`, or `undefined` for not at all. Each query word claims
- * a title word — whole, as its opening, or as an abbreviation of it (`flt cc` names
- * `Flight CC`) — the stronger claims taken first, so `c cc` names `CC Candidate`; a
- * word left over may claim a run of words whose openings it spells (`fcc`, `jqo`). The
- * title the query spells outright ranks first, then one it opens.
- */
-export declare function matchTitle(query: string, title: string): {
-    score: number;
-    strong: boolean;
-} | undefined;
-/** {@link matchTitle}'s score, `0` for no match. */
-export declare function matchScore(query: string, title: string): number;
-/** What a search reads of one list: its items and their ticks. */
-export interface Searchable<L> {
-    list: L;
-    schema: QuillFieldSchema;
-    value: Record<string, unknown> | undefined;
-}
-/**
- * The items across `lists` that `query` names, best first; a tie keeps the order of
- * `lists`, then of each list's items.
- */
-export declare function searchChecklists<L>(query: string, lists: readonly Searchable<L>[], limit?: number): ChecklistHit<L>[];

package/dist/visual/checklists.js

@@ -1,20 +1,3 @@
-/**
- * The document's checklists, and the search an open matrix's add box runs over them
- * (VISUAL_EDITOR §"The matrix"). The editor root publishes every card-level matrix off
- * the model it derives, so a list in a collapsed group or another card is searched
- * as surely as the one the author is typing in. A matrix mounted off-tree, or nested
- * in a container, is not indexed and searches its own items alone.
- */
-import { getContext, setContext } from 'svelte';
-import { addedItems, matrixHeld, matrixMembers, memberValue } from './structure.js';
-const KEY = Symbol('qm-checklists');
-export function setChecklists(index) {
-    setContext(KEY, index);
-}
-/** The index under a mounted editor; `undefined` off-tree. */
-export function checklists() {
-    return getContext(KEY);
-}
 /** The value a matrix prints: the stored map, else a mapping `default:`. */
 export function matrixPrinted(value, schema) {
     const map = (v) => typeof v === 'object' && v !== null && !Array.isArray(v)
@@ -22,150 +5,3 @@ export function matrixPrinted(value, schema) {
         : undefined;
     return value == null ? map(schema.default) : map(value);
 }
-/** Every card-level matrix of the cards, in document order. */
-export function cardChecklists(cards, cardLabel, path, leafKey, commit) {
-    const out = [];
-    for (const card of cards) {
-        if (card.unschemable)
-            continue;
-        for (const section of card.sections)
-            for (const f of section.fields) {
-                if (f.control !== 'matrix')
-                    continue;
-                const at = path(card, f.name);
-                if (at == null)
-                    continue;
-                out.push({
-                    key: leafKey(card, f.name),
-                    path: at,
-                    label: card.isMain ? f.label : `${f.label} · ${cardLabel(card)}`,
-                    schema: f.schema,
-                    value: matrixPrinted(card.values[f.name], f.schema),
-                    commit: (next) => commit(card, f.name, next)
-                });
-            }
-    }
-    return out;
-}
-/** Every item a matrix can show: the roster in declaration order, then the items its
- *  map adds, in id order. */
-export function checklistItems(schema, value) {
-    return [...matrixMembers(schema.members), ...addedItems(schema, value)];
-}
-/** Lowercase, unaccented words, any script: `Exec / Aide / CAG` → `exec aide cag`. */
-function words(s) {
-    return s
-        .normalize('NFKD')
-        .replace(/[\u0300-\u036f]/g, '')
-        .toLowerCase()
-        .split(/[^\p{L}\p{N}]+/u)
-        .filter(Boolean);
-}
-/** `flt` in `flight`: every letter in order, the first letters equal. */
-function abbreviates(token, word) {
-    if (token[0] !== word[0])
-        return false;
-    let i = 0;
-    for (const c of word)
-        if (c === token[i])
-            i++;
-    return i === token.length;
-}
-/** How a query word claims one title word: whole (3), as its opening (2), as an
- *  abbreviation (1), or not (0). */
-function claim(token, word) {
-    return word === token ? 3 : word.startsWith(token) ? 2 : abbreviates(token, word) ? 1 : 0;
-}
-/** The end of the run of free words from `i` whose openings spell `token` in order —
- *  `fcc` over `flight cc`, `jqo` over `joint qualified officer` — or `-1`. */
-function runFrom(token, w, free, i) {
-    if (i >= w.length || !free[i])
-        return -1;
-    for (let k = Math.min(token.length, w[i].length); k > 0; k--) {
-        if (!w[i].startsWith(token.slice(0, k)))
-            continue;
-        if (k === token.length)
-            return i + 1;
-        const end = runFrom(token.slice(k), w, free, i + 1);
-        if (end >= 0)
-            return end;
-    }
-    return -1;
-}
-/**
- * How well `query` names `title`, or `undefined` for not at all. Each query word claims
- * a title word — whole, as its opening, or as an abbreviation of it (`flt cc` names
- * `Flight CC`) — the stronger claims taken first, so `c cc` names `CC Candidate`; a
- * word left over may claim a run of words whose openings it spells (`fcc`, `jqo`). The
- * title the query spells outright ranks first, then one it opens.
- */
-export function matchTitle(query, title) {
-    const q = words(query);
-    const w = words(title);
-    if (!q.length || !w.length)
-        return undefined;
-    const free = w.map(() => true);
-    const left = q.map(() => true);
-    let score = 0;
-    let strong = true;
-    for (const level of [3, 2, 1])
-        q.forEach((token, t) => {
-            if (!left[t])
-                return;
-            const at = w.findIndex((word, i) => free[i] && claim(token, word) === level);
-            if (at < 0)
-                return;
-            free[at] = left[t] = false;
-            score += level;
-            if (level === 1)
-                strong = false;
-        });
-    for (let t = 0; t < q.length; t++) {
-        if (!left[t])
-            continue;
-        let found = false;
-        for (let i = 0; i < w.length && !found; i++) {
-            const end = runFrom(q[t], w, free, i);
-            if (end - i < 2)
-                continue;
-            for (let k = i; k < end; k++)
-                free[k] = false;
-            found = true;
-        }
-        if (!found)
-            return undefined;
-        score += 1;
-        strong = false;
-    }
-    const typed = q.join(' ');
-    const whole = w.join(' ');
-    return { score: score + (whole === typed ? 3 : whole.startsWith(typed) ? 1 : 0), strong };
-}
-/** {@link matchTitle}'s score, `0` for no match. */
-export function matchScore(query, title) {
-    return matchTitle(query, title)?.score ?? 0;
-}
-/**
- * The items across `lists` that `query` names, best first; a tie keeps the order of
- * `lists`, then of each list's items.
- */
-export function searchChecklists(query, lists, limit = 8) {
-    const hits = [];
-    for (const { list, schema, value } of lists)
-        for (const item of checklistItems(schema, value)) {
-            const match = matchTitle(query, item.title);
-            if (match)
-                hits.push({
-                    list,
-                    id: item.id,
-                    title: item.title,
-                    held: matrixHeld(memberValue(value, item.id)),
-                    ...match
-                });
-        }
-    return hits
-        .map((h, i) => [h, i])
-        .sort(([a, i], [b, j]) => b.score - a.score || i - j)
-        .slice(0, limit)
-        .map(([h]) => h);
-}

package/dist/visual/guidance.d.ts

@@ -0,0 +1,15 @@
+/** `Mod-/`, read off `key` so a layout that shifts to reach `/` still matches; either
+ *  modifier stands for `Mod`. */
+export declare function isGuidanceKey(e: KeyboardEvent): boolean;
+/**
+ * The guidance trigger for the description nearest `from`: the innermost element
+ * carrying `aria-describedby` whose ids name a parked description with a trigger
+ * beside it. A trigger points at its own parked node through that same attribute,
+ * which is the relation read here; ids that are not a description (an array's count,
+ * a prose leaf's note) are skipped, and an undescribed property falls through to the
+ * group around it.
+ */
+export declare function guidanceTrigger(from: Element, root: Element): HTMLElement | undefined;
+/** Root keydown: the key raises (or lowers) the nearest guidance. A trigger's `click()`
+ *  is an activation with no pointer behind it, which `FieldHint` toggles on. */
+export declare function raiseGuidance(e: KeyboardEvent): void;

package/dist/visual/guidance.js

@@ -0,0 +1,37 @@
+// The guidance key: `Mod-/` on a control raises the description that control carries,
+// the keyboard's way in to a `FieldHint` whose glyph is out of the tab order.
+/** `Mod-/`, read off `key` so a layout that shifts to reach `/` still matches; either
+ *  modifier stands for `Mod`. */
+export function isGuidanceKey(e) {
+    return e.key === '/' && (e.ctrlKey || e.metaKey) && !e.altKey && !e.isComposing;
+}
+/**
+ * The guidance trigger for the description nearest `from`: the innermost element
+ * carrying `aria-describedby` whose ids name a parked description with a trigger
+ * beside it. A trigger points at its own parked node through that same attribute,
+ * which is the relation read here; ids that are not a description (an array's count,
+ * a prose leaf's note) are skipped, and an undescribed property falls through to the
+ * group around it.
+ */
+export function guidanceTrigger(from, root) {
+    for (let el = from.closest('[aria-describedby]'); el;) {
+        for (const id of el.getAttribute('aria-describedby').split(/\s+/)) {
+            const trigger = root.querySelector(`.qm-field-hint[aria-describedby="${id}"]`);
+            if (trigger)
+                return trigger;
+        }
+        el = el.parentElement?.closest('[aria-describedby]') ?? null;
+    }
+    return undefined;
+}
+/** Root keydown: the key raises (or lowers) the nearest guidance. A trigger's `click()`
+ *  is an activation with no pointer behind it, which `FieldHint` toggles on. */
+export function raiseGuidance(e) {
+    if (!isGuidanceKey(e) || !(e.target instanceof Element))
+        return;
+    const trigger = guidanceTrigger(e.target, e.currentTarget);
+    if (!trigger)
+        return;
+    e.preventDefault();
+    trigger.click();
+}