@quillmark/svelte 0.5.1 → 0.7.0

package/dist/preset/recipes.css

@@ -8,11 +8,10 @@
    they freeze nothing about the surfaces' interior: the reason the package withholds
    its own internal classes does not reach them.
 
-   Unlayered, deliberately. `@layer qm` exists so consumer CSS beats the surfaces
-   without `!important`, and the same has to be true here; a layer of the preset's own
-   would put a second name in the contract and change what `revert-layer` at the foot
-   of this file resolves against. Unlayered, a consumer's own rules win by ordinary
-   precedence and the focus rule works with nothing declared. */
+   Unlayered, deliberately: a layer of the preset's own would put a name in the contract,
+   and unlayered a consumer's rules win over these by ordinary precedence. Ordinary
+   specificity too, not the surfaces' `:where()` zero: a consumer takes these classes on
+   purpose, so a rule of their own beside one is aimed rather than incidental. */
 
 /* ── The page ──────────────────────────────────────────────────────────────── */
 
@@ -51,11 +50,19 @@
    root scroller counting the overflow its panes clip, and a wheel over the chrome drags
    the whole app off the top. Three bands (a head, the body, an optional foot), and the
    body takes what is left and may shrink below its content, so the panes in it own
-   their overflow and hold still while their contents move. */
+   their overflow and hold still while their contents move.
+
+   The one column is stated for the same reason the rows are: an implicit track is `auto`,
+   which is sized by what a band holds, and a `.qm-split` under one contributes its items'
+   max-content through its `fr` tracks. The shell would take the width of the widest thing
+   mounted in it instead of the viewport's, and every band would be that wide with the
+   second pane past the edge. A host holding its content to a maximum never sees it; one
+   spending the whole screen sees it on the first surface it mounts. */
 .qm-workspace {
 	position: fixed;
 	inset: 0;
 	display: grid;
+	grid-template-columns: minmax(0, 1fr);
 	grid-template-rows: auto minmax(0, 1fr) auto;
 	overflow: hidden;
 }
@@ -116,9 +123,12 @@ html:has(.qm-workspace) {
    pane needs no `inert` and the host needs no breakpoint in JS. Both stay mounted (a
    preview binds its handle once, an editor holds a caret, a history and a scroll), so
    the switch is presentational, never conditional. A pane hidden this way keeps the
-   pixels it had (the paint loop's band sweep no-ops on an empty visible set) and repaints
-   from its live box when it comes back, which its resize observer sees as a width moving
-   off zero.
+   pixels it had: the paint loop's band sweep no-ops on an empty visible set, and its
+   resize observer holds the last real width rather than rastering at the 0×0 box a hidden
+   pane reports, so what comes back at the width it left needs no paint at all. The
+   preview's caret follow spans the same window — a trip asked for against a pane with no
+   box is held and run when it has one (`preview/bridge.ts`), the pane opening at the
+   caret rather than several edits behind it.
 
    Height is the second clause because a landscape phone passes the first one: it clears
    the width with room for two tracks and has no body left to put them in. A desktop window
@@ -308,18 +318,12 @@ pre.qm-readout {
 
 /* One visible indicator for the whole host, since none of these controls draws a ring
    of its own. It reads the ink rung rather than a hue: the page is monochrome, and a
-   focus ring is a position, not a destination. */
-:focus-visible {
+   focus ring is a position, not a destination.
+
+   The mounted surfaces are cut out of it: they draw their own ring, and a blanket would
+   repaint the controls that already have one. `:not(:where(…))` contributes no
+   specificity, so the cut-out leaves this rule's own rank where it was. */
+:focus-visible:not(:where([data-qm-root], [data-qm-root] *)) {
 	outline: var(--qmh-ring-width) solid var(--qmh-ink);
 	outline-offset: var(--qmh-space-half);
 }
-
-/* The mounted surfaces are the exception, and the rule above is why: an unlayered host
-   declaration beats `@layer qm.chrome` by design, so a ring written for controls that
-   draw none repaints the ones that do. `revert-layer` hands each control back to the
-   layer under this one, which is the package's own ring at its own offset, and is
-   what makes this file's own lack of a layer load-bearing rather than a preference. */
-[data-qm-root] :focus-visible {
-	outline: revert-layer;
-	outline-offset: revert-layer;
-}

package/dist/preview/Preview.svelte

@@ -101,8 +101,10 @@
 	   the surface's own, so a bare `<div>` is a mounting site. The
 	   padding is safe against the paint loop: a slot is a `width: 100%` child and
 	   measures the content box, and the container's own `clientWidth` is read only as
-	   a change detector, which a constant inset does not disturb. */
-	.qm-preview {
+	   a change detector, which a constant inset does not disturb.
+
+	   `:global(:where(…))` puts this promised class at zero rank (ARCHITECTURE §Styling). */
+	:global(:where(.qm-preview)) {
 		box-sizing: border-box;
 		position: relative;
 		width: 100%;

package/dist/preview/bridge.d.ts

@@ -1,6 +1,8 @@
 import type { LiveSession } from '@quillmark/wasm';
 import type { Landing } from '../core/address.js';
 import type { PageSlot } from './paint.js';
+/** Both trips are held while the pane has no box to measure against, and the last one
+ *  held runs when it has one again. */
 export interface BridgeController {
     /** Scroll `field`'s first box to centre; `false` when this compile places none
      *  for that address, which is the whole of what the preview can say about it. */
@@ -12,4 +14,25 @@ export interface BridgeController {
     focusPosition(field: string, pos: number): void;
     destroy(): void;
 }
+/** The vertical extent the fold test reads; a `DOMRect` is one. */
+export interface VerticalSpan {
+    top: number;
+    bottom: number;
+    height: number;
+}
+/**
+ * Whether `target` sits clear of `port`'s edges by the fold's clearance, which is the
+ * target's own height: a caret rect flush against an edge is visible and unusable, and
+ * the next line typed lands past it. Derived from the target rather than a margin dial,
+ * so it scales with zoom exactly as the caret does, and bounded at both ends so the
+ * answer is reachable across the whole range of targets a compile locates.
+ *
+ * The floor is what a zero-height rect gets, which bare intersection would score as
+ * clear at either edge. The cap is a third of the room the port has to spare, so a
+ * target too tall for its own height of clearance — a located line at zoom, a short
+ * split track — passes once centred and holds a band around it, rather than being
+ * re-centred by every keystroke. A target taller than the port is clear while it covers
+ * the port: no scroll shows more of it.
+ */
+export declare function clearOfTheFold(target: VerticalSpan, port: VerticalSpan): boolean;
 export declare function createBridge(session: LiveSession, container: HTMLElement, slots: readonly PageSlot[], onPick: ((at: Landing) => void) | undefined): BridgeController;

package/dist/preview/bridge.js

@@ -1,4 +1,34 @@
 import { boxesForField, rectToPercent, clickToPdfPt, applyPercentRect } from './geometry.js';
+/** A pane hidden by the shell's narrow switch (`preset/recipes.css`) measures 0×0, and so
+ *  does every box on it: the clearance arithmetic reads that as a caret clear of both
+ *  edges, and a centring computes its trip out of zeros. Neither is an answer about where
+ *  the caret is. */
+function hasBox(port) {
+    return port.width > 0 && port.height > 0;
+}
+/** What a rect reporting no height clears an edge by, in CSS px: a caret's own at the
+ *  smallest zoom a page still reads at. */
+const MIN_CLEARANCE = 8;
+/**
+ * Whether `target` sits clear of `port`'s edges by the fold's clearance, which is the
+ * target's own height: a caret rect flush against an edge is visible and unusable, and
+ * the next line typed lands past it. Derived from the target rather than a margin dial,
+ * so it scales with zoom exactly as the caret does, and bounded at both ends so the
+ * answer is reachable across the whole range of targets a compile locates.
+ *
+ * The floor is what a zero-height rect gets, which bare intersection would score as
+ * clear at either edge. The cap is a third of the room the port has to spare, so a
+ * target too tall for its own height of clearance — a located line at zoom, a short
+ * split track — passes once centred and holds a band around it, rather than being
+ * re-centred by every keystroke. A target taller than the port is clear while it covers
+ * the port: no scroll shows more of it.
+ */
+export function clearOfTheFold(target, port) {
+    if (target.height >= port.height)
+        return target.top <= port.top && target.bottom >= port.bottom;
+    const clearance = Math.min(Math.max(target.height, MIN_CLEARANCE), (port.height - target.height) / 3);
+    return target.top - clearance >= port.top && target.bottom + clearance <= port.bottom;
+}
 export function createBridge(session, container, slots, onPick) {
     const unlisten = [];
     // Two rungs: `positionAt` over span-tracked content, `fieldAt` over every placement
@@ -53,43 +83,70 @@ export function createBridge(session, container, slots, onPick) {
         else if (target.right > port.right)
             container.scrollLeft += target.right - port.right;
     }
-    // Clear of the fold is the target's own height of clearance at each edge, not bare
-    // intersection: a caret rect flush against one is visible and unusable, and the
-    // next line typed lands past it. Derived from the target rather than a margin
-    // dial, so it scales with zoom exactly as the caret does.
-    function clearOfTheFold(target) {
-        const port = container.getBoundingClientRect();
-        return target.top - target.height >= port.top && target.bottom + target.height <= port.bottom;
+    // The trip a pane with no box could not run, held for the box coming back. One, and
+    // the last one asked for: a caret hop supersedes the hop before it on a showing pane
+    // too.
+    let held;
+    // The re-assert. Nothing else asks on the way back: `refresh` re-asks only on a
+    // recompile, and the reader who has just tapped Preview is not typing, so the pane
+    // would open where the caret was several edits ago. Guarded for jsdom, which ships no
+    // ResizeObserver and lays out nothing for one to report.
+    if (typeof ResizeObserver !== 'undefined') {
+        const observer = new ResizeObserver(() => {
+            if (!held || !hasBox(container.getBoundingClientRect()))
+                return;
+            const trip = held;
+            held = undefined;
+            trip();
+        });
+        observer.observe(container);
+        unlisten.push(() => observer.disconnect());
     }
-    return {
-        scrollToField(field) {
-            const box = boxesForField(field, session.fieldBoxes(field), session.regions())[0];
-            if (!box)
-                return false;
-            const slot = slots[box.page];
-            if (!slot)
-                return false;
-            // A discrete act ("show me this field"), so it centres every time, unlike
-            // the continuous hop below.
-            centre(measure(slot, rectToPercent(box.rect, slot.size)));
+    function scrollToField(field) {
+        const box = boxesForField(field, session.fieldBoxes(field), session.regions())[0];
+        if (!box)
+            return false;
+        const slot = slots[box.page];
+        if (!slot)
+            return false;
+        // The address is placed, which is the whole of what the `boolean` answers; a pane
+        // with no box yet is not a second no.
+        if (!hasBox(container.getBoundingClientRect())) {
+            held = () => void scrollToField(field);
             return true;
-        },
-        focusPosition(field, pos) {
-            const region = session.locate(field, pos);
-            if (!region)
-                return;
-            const slot = slots[region.page];
-            if (!slot)
-                return;
-            // The continuous hop: one call per keystroke and per arrow key, so it moves
-            // the pane only when the caret has left the fold. Centring unconditionally
-            // takes the scrollport back from the user on every one of them, including
-            // the ones that changed nothing about where the caret already was.
-            const target = measure(slot, rectToPercent(region.rect, slot.size));
-            if (clearOfTheFold(target))
-                return;
-            centre(target);
-        },
+        }
+        // A discrete act ("show me this field"), so it centres every time, unlike
+        // the continuous hop below.
+        centre(measure(slot, rectToPercent(box.rect, slot.size)));
+        return true;
+    }
+    function focusPosition(field, pos) {
+        const region = session.locate(field, pos);
+        if (!region)
+            return;
+        const slot = slots[region.page];
+        if (!slot)
+            return;
+        // Held before the guard below, which a pane measuring zero answers "already clear"
+        // for every keystroke of (`hasBox`): the follow would die silently for as long as
+        // a track is hidden. What is held is the request, not the trip, so it re-locates
+        // against whatever compile is current when the pane comes back.
+        if (!hasBox(container.getBoundingClientRect())) {
+            held = () => focusPosition(field, pos);
+            return;
+        }
+        // The continuous hop: one call per keystroke and per arrow key, so it moves
+        // the pane only when the caret has left the fold. Centring unconditionally
+        // takes the scrollport back from the user on every one of them, including
+        // the ones that changed nothing about where the caret already was.
+        const target = measure(slot, rectToPercent(region.rect, slot.size));
+        if (clearOfTheFold(target, container.getBoundingClientRect()))
+            return;
+        centre(target);
+    }
+    return {
+        scrollToField,
+        focusPosition,
         destroy() {
             for (const off of unlisten)
                 off();

package/dist/preview/controller.d.ts

@@ -23,10 +23,11 @@ export interface PreviewController {
      *  apply-driven hop. */
     refresh(change: ChangeSet): void;
     /**
-     * Scroll `field`'s first box into view. `false` when this compile places nothing
-     * at that address — an answer, not a failure: the plate places plenty it does not
-     * track, and the preview carries no schema to tell that from a field the host
-     * misnamed. The editor's `focusField` is what distinguishes them.
+     * Scroll `field`'s first box into view, and end any follow it outranks. `false`
+     * when this compile places nothing at that address — an answer, not a failure: the
+     * plate places plenty it does not track, and the preview carries no schema to tell
+     * that from a field the host misnamed. The editor's `focusField` is what
+     * distinguishes them.
      */
     scrollToField(field: DocPath): boolean;
     /**
@@ -40,7 +41,7 @@ export interface PreviewController {
     focusPosition(at: Place): void;
     /**
      * End the follow: the pane stays where the user left it until the next
-     * `focusPosition`.
+     * `focusPosition`. A `scrollToField` that placed its target ends one too.
      *
      * The editor's `onActiveLeafChange` is the signal, firing for a form control as for
      * a prose leaf: `onActiveLeafChange={preview.endFollow}`. A control has no caret

package/dist/preview/controller.js

@@ -84,12 +84,12 @@ export function createPreview(session, opts) {
     }
     render(session.pageCount, []);
     // The last place the editor put the caret, re-located after every recompile and
-    // dropped on a focus change. `session.locate` answers against the last compiled
-    // layout and a consumer debounces `update`, so a caret typed past that layout's
-    // content is off-content for the whole burst: `focusPosition` no-ops and the pane
-    // sits still, and a caret event is otherwise the only thing that asks again. The
-    // re-locate is the preview's, not the consumer's: the staleness sits between two
-    // session queries this module owns both ends of.
+    // dropped on a focus change or a discrete hop. `session.locate` answers against the
+    // last compiled layout and a consumer debounces `update`, so a caret typed past that
+    // layout's content is off-content for the whole burst: `focusPosition` no-ops and
+    // the pane sits still, and a caret event is otherwise the only thing that asks
+    // again. The re-locate is the preview's, not the consumer's: the staleness sits
+    // between two session queries this module owns both ends of.
     let followed;
     return {
         refresh(change) {
@@ -100,7 +100,13 @@ export function createPreview(session, opts) {
                 bridge?.focusPosition(followed.field, followed.pos);
         },
         scrollToField(field) {
-            return bridge?.scrollToField(field) ?? false;
+            const placed = bridge?.scrollToField(field) ?? false;
+            // The discrete hop outranks the follow: a caret re-asserted at the next
+            // recompile would pull the pane straight off the field a host just asked
+            // for. A hop that placed nothing moved nothing, so the follow stands.
+            if (placed)
+                followed = undefined;
+            return placed;
         },
         focusPosition(at) {
             followed = at;

package/dist/preview/geometry.d.ts

@@ -14,17 +14,18 @@ export interface PdfPoint {
     y: number;
 }
 /**
- * An address's boxes: `fieldBoxes`'s union, else its own `regions()` rects, else the
- * rects of everything under it. What the scroll reads, so an address `regions()`
- * names is never one the preview cannot place (PREVIEW.md §"Two responsibilities").
+ * An address's boxes: `fieldBoxes`'s union, else every `regions()` rect at or under it.
+ * What the scroll reads, so an address `regions()` names is never one the preview
+ * cannot place (PREVIEW.md §"Two responsibilities").
  *
  * `fieldBoxes` answers `[]` for a scalar reference the plate places without tracking
- * its content and for a `richtext[]` element; runtime.d.ts says what such a field's
- * box is, a single `regions()` rect. The third rung is that sentence one granularity
- * down — an array's ink is its elements' — and is a fallback, not a union, so an
- * address with rects of its own never also draws its children's. The boundary
- * character (`.` for a nested field, `[` for an array element) keeps the prefix a
- * path boundary: `main.keywords` matches `main.keywords[0]`, not
+ * its content and for an array itself; runtime.d.ts says what such a field's box is, a
+ * single `regions()` rect. The second rung takes an address and its descendants
+ * together, since a container holds both: a plate composing an array's presentation
+ * regions the array on the ink it composed — a separator, a heading — where each
+ * element regions the ink it carries itself, and the field is placed at all of it. The
+ * boundary character (`.` for a nested field, `[` for an array element) keeps the
+ * prefix a path boundary: `main.keywords` matches `main.keywords[0]`, not
  * `main.keywords_note`.
  */
 export declare function boxesForField(field: string, boxes: readonly FieldRegion[], regions: readonly FieldRegion[]): readonly FieldRegion[];

package/dist/preview/geometry.js

@@ -1,24 +1,22 @@
 /**
- * An address's boxes: `fieldBoxes`'s union, else its own `regions()` rects, else the
- * rects of everything under it. What the scroll reads, so an address `regions()`
- * names is never one the preview cannot place (PREVIEW.md §"Two responsibilities").
+ * An address's boxes: `fieldBoxes`'s union, else every `regions()` rect at or under it.
+ * What the scroll reads, so an address `regions()` names is never one the preview
+ * cannot place (PREVIEW.md §"Two responsibilities").
  *
  * `fieldBoxes` answers `[]` for a scalar reference the plate places without tracking
- * its content and for a `richtext[]` element; runtime.d.ts says what such a field's
- * box is, a single `regions()` rect. The third rung is that sentence one granularity
- * down — an array's ink is its elements' — and is a fallback, not a union, so an
- * address with rects of its own never also draws its children's. The boundary
- * character (`.` for a nested field, `[` for an array element) keeps the prefix a
- * path boundary: `main.keywords` matches `main.keywords[0]`, not
+ * its content and for an array itself; runtime.d.ts says what such a field's box is, a
+ * single `regions()` rect. The second rung takes an address and its descendants
+ * together, since a container holds both: a plate composing an array's presentation
+ * regions the array on the ink it composed — a separator, a heading — where each
+ * element regions the ink it carries itself, and the field is placed at all of it. The
+ * boundary character (`.` for a nested field, `[` for an array element) keeps the
+ * prefix a path boundary: `main.keywords` matches `main.keywords[0]`, not
  * `main.keywords_note`.
  */
 export function boxesForField(field, boxes, regions) {
     if (boxes.length)
         return boxes;
-    const own = regions.filter((r) => r.field === field);
-    if (own.length)
-        return own;
-    return regions.filter((r) => r.field.startsWith(`${field}.`) || r.field.startsWith(`${field}[`));
+    return regions.filter((r) => r.field === field || r.field.startsWith(`${field}.`) || r.field.startsWith(`${field}[`));
 }
 /**
  * Forward: a PDF-pt rect -> CSS % of the page box. Percent positioning tracks

package/dist/preview/index.js

@@ -4,13 +4,14 @@
 // land here. Reserved-package invariant: this subpath imports no editor-side code
 // (the codec, the VisualEditor) so a `@quillmark/preview` promotion stays a
 // re-export, not a refactor: it may reach `/core` (the shared WASM boundary) and
-// nothing else. Enforced by `check:deps`, which walks the subpath's import graph.
+// nothing else. Enforced by `check:deps`, at the subpath's edge: a relative hop past a
+// module directly in `core/` is what pulls the codec, and all of ProseMirror with it.
 // The theme derivation, which the page slots read through `var()`.
 // Imported at the barrel because a subpath is what a consumer gets: this surface
 // reaches modules inside `core/` and never its entry, so a sheet hanging off that
 // entry arrives only for a consumer importing `/core` for some other reason. The
 // sheet rather than the entry, because the barrel needs the derivation and not
-// `init`. `check:deps` (rule 4) walks this file's own graph and holds the reach.
+// `init`. `check:deps` holds the reach.
 import '../core/theme.css';
 export { createPreview } from './controller.js';
 export { default as Preview } from './Preview.svelte';

package/dist/preview/paint.js

@@ -192,9 +192,17 @@ onPaintError) {
             return;
         rafId = requestAnimationFrame(() => {
             rafId = 0;
+            const width = container.clientWidth;
+            // A pane the shell has hidden reports a 0×0 box, which is a width to paint
+            // nothing at rather than a width that moved: `paintSlot` would take its
+            // `clientWidth || widthPt` fallback and freeze every mounted canvas at the 1×
+            // raster. The last real width and any pending force are held instead — the
+            // observer fires again when the pane has a box, and a return at that same
+            // width needs no raster, the pixels being the ones it was hidden with.
+            if (width === 0)
+                return;
             const forced = forcePending;
             forcePending = false;
-            const width = container.clientWidth;
             if (!forced && width === lastWidth)
                 return;
             lastWidth = width;