@capacms/sdk 1.0.0-next.1 → 1.0.0-next.2

package/README.md

@@ -419,6 +419,14 @@ every navigation, `select { entryId, field }` on a click, and `hover`.
 `acceptMessage(event, allowedOrigins, parent)` is the site's filter, exported
 for your own tests.
 
+Since 1.0.0-next.2 the site also sends `visible { entryId, field }` while the
+page scrolls (at most every 150ms, and only when it changes): the tagged element
+at the centre of the viewport, chosen by `pickCentred`. At the very top of a
+page, where a heading can never reach the centre, it is the topmost visible
+element instead, and at the very bottom the bottommost. The editor's "Follow the
+page" scrolls the form to that field. It is additive and still `v: 1`: an older
+overlay never sends it and the editor simply does not follow.
+
 ## Not yet
 
 `--select-from-depth`, `capa convert-url`, `capa persist`, GraphQL, and `/api/`

package/dist/overlay/index.d.ts

@@ -1,5 +1,5 @@
-export { acceptMessage, hoverMessage, normaliseOrigins, readyMessage, selectMessage, ADMIN_SOURCE, PROTOCOL_VERSION, SITE_SOURCE, } from "./protocol";
-export type { AdminMessage, MessageLike, SiteMessage } from "./protocol";
+export { acceptMessage, hoverMessage, normaliseOrigins, pickCentred, readyMessage, scrollEdge, selectMessage, visibleMessage, ADMIN_SOURCE, PROTOCOL_VERSION, SITE_SOURCE, } from "./protocol";
+export type { AdminMessage, MessageLike, SiteMessage, TaggedBox } from "./protocol";
 export interface OverlayOptions {
     /**
      * The Capa admin origins allowed to drive this page, for example

package/dist/overlay/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SITE_SOURCE = exports.PROTOCOL_VERSION = exports.ADMIN_SOURCE = exports.selectMessage = exports.readyMessage = exports.normaliseOrigins = exports.hoverMessage = exports.acceptMessage = void 0;
+exports.SITE_SOURCE = exports.PROTOCOL_VERSION = exports.ADMIN_SOURCE = exports.visibleMessage = exports.selectMessage = exports.scrollEdge = exports.readyMessage = exports.pickCentred = exports.normaliseOrigins = exports.hoverMessage = exports.acceptMessage = void 0;
 exports.startOverlay = startOverlay;
 /**
  * `@capacms/sdk/overlay`: the site half of Capa's live preview.
@@ -21,8 +21,11 @@ var protocol_2 = require("./protocol");
 Object.defineProperty(exports, "acceptMessage", { enumerable: true, get: function () { return protocol_2.acceptMessage; } });
 Object.defineProperty(exports, "hoverMessage", { enumerable: true, get: function () { return protocol_2.hoverMessage; } });
 Object.defineProperty(exports, "normaliseOrigins", { enumerable: true, get: function () { return protocol_2.normaliseOrigins; } });
+Object.defineProperty(exports, "pickCentred", { enumerable: true, get: function () { return protocol_2.pickCentred; } });
 Object.defineProperty(exports, "readyMessage", { enumerable: true, get: function () { return protocol_2.readyMessage; } });
+Object.defineProperty(exports, "scrollEdge", { enumerable: true, get: function () { return protocol_2.scrollEdge; } });
 Object.defineProperty(exports, "selectMessage", { enumerable: true, get: function () { return protocol_2.selectMessage; } });
+Object.defineProperty(exports, "visibleMessage", { enumerable: true, get: function () { return protocol_2.visibleMessage; } });
 Object.defineProperty(exports, "ADMIN_SOURCE", { enumerable: true, get: function () { return protocol_2.ADMIN_SOURCE; } });
 Object.defineProperty(exports, "PROTOCOL_VERSION", { enumerable: true, get: function () { return protocol_2.PROTOCOL_VERSION; } });
 Object.defineProperty(exports, "SITE_SOURCE", { enumerable: true, get: function () { return protocol_2.SITE_SOURCE; } });
@@ -32,6 +35,8 @@ const TAGGED = "[data-capa-entry][data-capa-field]";
 const SCROLL_KEY = "capa-overlay:scrollY";
 /** How long a refresh keeps putting the scroll position back while the page re-renders. */
 const RESTORE_WINDOW_MS = 1500;
+/** `visible` is sent at most this often while the page scrolls. */
+const VISIBLE_THROTTLE_MS = 150;
 const noop = () => { };
 let running = null;
 /**
@@ -67,6 +72,8 @@ function createOverlay(initial) {
     let readyFrame = 0;
     let hoverFrame = 0;
     let lastPointer = null;
+    let visibleTimer = 0;
+    let lastVisible = "";
     const post = (message) => {
         if (!adminOrigin)
             return;
@@ -195,6 +202,41 @@ function createOverlay(initial) {
             return;
         readyFrame = window.requestAnimationFrame(() => sendReady(false));
     };
+    // ------------------------------------------------------------- visible ---
+    /**
+     * Which tagged element sits at the centre of the viewport, reported when it
+     * changes. The editor's "Follow the page" scrolls the form to match. Sent
+     * only to an admin that has said hello, and only on a change, so a still
+     * page sends nothing.
+     */
+    const reportVisible = () => {
+        visibleTimer = 0;
+        if (!adminOrigin)
+            return;
+        const boxes = tagged().map((el) => {
+            const rect = el.getBoundingClientRect();
+            return {
+                entryId: el.getAttribute("data-capa-entry") ?? "",
+                field: el.getAttribute("data-capa-field") ?? "",
+                top: rect.top,
+                bottom: rect.bottom,
+            };
+        });
+        const edge = (0, protocol_1.scrollEdge)(window.scrollY, window.innerHeight, document.documentElement.scrollHeight);
+        const pick = (0, protocol_1.pickCentred)(boxes, window.innerHeight, edge);
+        if (!pick)
+            return;
+        const key = `${pick.entryId}\n${pick.field}`;
+        if (key === lastVisible)
+            return;
+        lastVisible = key;
+        post((0, protocol_1.visibleMessage)(pick.entryId, pick.field));
+    };
+    const onScroll = () => {
+        render();
+        if (!visibleTimer)
+            visibleTimer = window.setTimeout(reportVisible, VISIBLE_THROTTLE_MS);
+    };
     // -------------------------------------------------------------- scroll ---
     const restoreScroll = () => {
         if (!pendingScroll)
@@ -247,6 +289,7 @@ function createOverlay(initial) {
         switch (message.type) {
             case "hello":
                 adminOrigin = event.origin;
+                lastVisible = "";
                 sendReady(true);
                 render();
                 return;
@@ -321,7 +364,7 @@ function createOverlay(initial) {
         restoreScroll();
     });
     window.addEventListener("message", onMessage);
-    window.addEventListener("scroll", render, { capture: true, passive: true });
+    window.addEventListener("scroll", onScroll, { capture: true, passive: true });
     window.addEventListener("resize", render, { passive: true });
     window.addEventListener("popstate", scheduleReady);
     document.addEventListener("click", onClick, true);
@@ -330,7 +373,7 @@ function createOverlay(initial) {
     observer.observe(document.body, { childList: true, subtree: true, characterData: true });
     const dispose = () => {
         window.removeEventListener("message", onMessage);
-        window.removeEventListener("scroll", render, { capture: true });
+        window.removeEventListener("scroll", onScroll, { capture: true });
         window.removeEventListener("resize", render);
         window.removeEventListener("popstate", scheduleReady);
         document.removeEventListener("click", onClick, true);
@@ -340,6 +383,8 @@ function createOverlay(initial) {
         for (const id of [frame, readyFrame, hoverFrame])
             if (id)
                 window.cancelAnimationFrame(id);
+        if (visibleTimer)
+            window.clearTimeout(visibleTimer);
         layer?.remove();
         layer = null;
         if (running?.dispose === dispose)

package/dist/overlay/protocol.d.ts

@@ -15,6 +15,13 @@
  *     ready     { path, entries }                    after hello, and after every navigation
  *     select    { entryId, field }                   a tagged element was clicked
  *     hover     { entryId, field } | { entryId: "", field: null }
+ *     visible   { entryId, field }                   the tagged element at the centre of the
+ *                                                    viewport changed (throttled, on scroll)
+ *
+ * `visible` arrived in 1.0.0-next.2 and is OPTIONAL: it is still `v: 1`,
+ * because an admin that does not know it drops an unknown type, and an older
+ * overlay simply never sends it. Additive messages keep the version; only a
+ * change to an existing shape would move it.
  *
  * The admin keeps its own copy of these shapes (`apps/admin`, no dependency on
  * this package). If you change one side, change the other.
@@ -60,6 +67,12 @@ export type SiteMessage = {
     type: "hover";
     entryId: string;
     field: string | null;
+} | {
+    source: typeof SITE_SOURCE;
+    v: 1;
+    type: "visible";
+    entryId: string;
+    field: string;
 };
 /** The parts of a `MessageEvent` the filter reads, so a test can hand in a literal. */
 export interface MessageLike {
@@ -89,3 +102,33 @@ export declare function acceptMessage(event: MessageLike, allowedOrigins: readon
 export declare function readyMessage(path: string, entries: string[]): SiteMessage;
 export declare function selectMessage(entryId: string, field: string): SiteMessage;
 export declare function hoverMessage(entryId: string, field: string | null): SiteMessage;
+export declare function visibleMessage(entryId: string, field: string): SiteMessage;
+/** The part of a tagged element `pickCentred` reads, so a test can hand in literals. */
+export interface TaggedBox {
+    entryId: string;
+    field: string;
+    /** `getBoundingClientRect()`, viewport coordinates. */
+    top: number;
+    bottom: number;
+}
+/**
+ * The tagged element a reader is looking at: the one that contains the
+ * viewport's horizontal centre line, and when several do (a field inside a
+ * card that is also tagged) the SMALLEST, because the innermost element is
+ * the specific one. When none crosses the line, the nearest one that is at
+ * least partly on screen. Null when nothing tagged is on screen at all.
+ *
+ * `edge` is where the page is scrolled to. A heading near the top of a page
+ * can never reach the centre line, because the page cannot scroll above its
+ * top; at the top the topmost visible element is the one being read, and at
+ * the bottom the bottommost. The same rule a table of contents' scroll spy
+ * uses.
+ *
+ * Pure, so the admin's "follow the page" can be tested without a DOM.
+ */
+export declare function pickCentred(boxes: readonly TaggedBox[], viewportHeight: number, edge?: "top" | "bottom" | null): TaggedBox | null;
+/**
+ * Which edge a scroll position is at, for `pickCentred`. A page that does not
+ * scroll at all is at neither: nothing moves, and the centre rule stands.
+ */
+export declare function scrollEdge(scrollY: number, viewportHeight: number, scrollHeight: number): "top" | "bottom" | null;

package/dist/overlay/protocol.js

@@ -16,6 +16,13 @@
  *     ready     { path, entries }                    after hello, and after every navigation
  *     select    { entryId, field }                   a tagged element was clicked
  *     hover     { entryId, field } | { entryId: "", field: null }
+ *     visible   { entryId, field }                   the tagged element at the centre of the
+ *                                                    viewport changed (throttled, on scroll)
+ *
+ * `visible` arrived in 1.0.0-next.2 and is OPTIONAL: it is still `v: 1`,
+ * because an admin that does not know it drops an unknown type, and an older
+ * overlay simply never sends it. Additive messages keep the version; only a
+ * change to an existing shape would move it.
  *
  * The admin keeps its own copy of these shapes (`apps/admin`, no dependency on
  * this package). If you change one side, change the other.
@@ -27,6 +34,9 @@ exports.acceptMessage = acceptMessage;
 exports.readyMessage = readyMessage;
 exports.selectMessage = selectMessage;
 exports.hoverMessage = hoverMessage;
+exports.visibleMessage = visibleMessage;
+exports.pickCentred = pickCentred;
+exports.scrollEdge = scrollEdge;
 exports.PROTOCOL_VERSION = 1;
 exports.ADMIN_SOURCE = "capa-admin";
 exports.SITE_SOURCE = "capa";
@@ -104,3 +114,71 @@ function hoverMessage(entryId, field) {
         ? { source: exports.SITE_SOURCE, v: 1, type: "hover", entryId: "", field: null }
         : { source: exports.SITE_SOURCE, v: 1, type: "hover", entryId, field };
 }
+function visibleMessage(entryId, field) {
+    return { source: exports.SITE_SOURCE, v: 1, type: "visible", entryId, field };
+}
+/** Above any element height, so a box that misses the centre line never outranks one that crosses it. */
+const MISS_FLOOR = 1e9;
+/**
+ * The tagged element a reader is looking at: the one that contains the
+ * viewport's horizontal centre line, and when several do (a field inside a
+ * card that is also tagged) the SMALLEST, because the innermost element is
+ * the specific one. When none crosses the line, the nearest one that is at
+ * least partly on screen. Null when nothing tagged is on screen at all.
+ *
+ * `edge` is where the page is scrolled to. A heading near the top of a page
+ * can never reach the centre line, because the page cannot scroll above its
+ * top; at the top the topmost visible element is the one being read, and at
+ * the bottom the bottommost. The same rule a table of contents' scroll spy
+ * uses.
+ *
+ * Pure, so the admin's "follow the page" can be tested without a DOM.
+ */
+function pickCentred(boxes, viewportHeight, edge = null) {
+    const centre = viewportHeight / 2;
+    let best = null;
+    let bestScore = Infinity;
+    for (const b of boxes) {
+        if (!b.entryId || !b.field)
+            continue;
+        if (b.bottom <= 0 || b.top >= viewportHeight || b.bottom <= b.top)
+            continue;
+        const height = b.bottom - b.top;
+        let score;
+        if (edge === "top") {
+            // Topmost first; of two that start together, the smaller (inner) one.
+            score = b.top * MISS_FLOOR + height;
+        }
+        else if (edge === "bottom") {
+            score = (viewportHeight - b.bottom) * MISS_FLOOR + height;
+        }
+        else {
+            // Crossing the line scores by height (smaller wins) and always beats a
+            // box that misses it, which scores by its distance from the line on top
+            // of a floor no height can reach.
+            score =
+                b.top <= centre && b.bottom >= centre
+                    ? height
+                    : MISS_FLOOR + Math.min(Math.abs(b.top - centre), Math.abs(b.bottom - centre));
+        }
+        if (score < bestScore) {
+            best = b;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+/**
+ * Which edge a scroll position is at, for `pickCentred`. A page that does not
+ * scroll at all is at neither: nothing moves, and the centre rule stands.
+ */
+function scrollEdge(scrollY, viewportHeight, scrollHeight) {
+    const max = scrollHeight - viewportHeight;
+    if (max <= 1)
+        return null;
+    if (scrollY <= 1)
+        return "top";
+    if (scrollY >= max - 1)
+        return "bottom";
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capacms/sdk",
-  "version": "1.0.0-next.1",
+  "version": "1.0.0-next.2",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",