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

package/dist/overlay/protocol.d.ts

@@ -10,11 +10,30 @@
  *     highlight { entryId, field: string | null }    entryId "" clears
  *     outline   { on: boolean }                      outline every tagged element
  *     refresh   {}                                   re-render the draft
+ *     patch     { entryId, fields: [{ field, value, saved }] }
+ *                                                    unsaved text, as the editor types it
  *
  *   site -> admin  (source "capa")
- *     ready     { path, entries }                    after hello, and after every navigation
+ *     ready     { path, entries, features }          after hello, and after every navigation.
+ *                                                    `features`: what this overlay can do
+ *                                                    beyond v1 (`SITE_FEATURES`)
  *     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. `patch` and `features` are the
+ * same kind of addition: an admin sends `patch` only to an overlay whose
+ * `ready` lists "patch", and an older admin never reads `features`.
+ *
+ * A PATCH IS TEXT ONLY, and only where the page shows the field verbatim. The
+ * overlay changes a tagged element's text while it reads exactly `saved` (the
+ * value the page was rendered from) or what this page last patched it to, so
+ * a field the site formats (a price, a date, Markdown) is left alone until the
+ * save re-renders it (`patchedText`).
  *
  * The admin keeps its own copy of these shapes (`apps/admin`, no dependency on
  * this package). If you change one side, change the other.
@@ -22,6 +41,17 @@
 export declare const PROTOCOL_VERSION = 1;
 export declare const ADMIN_SOURCE = "capa-admin";
 export declare const SITE_SOURCE = "capa";
+/** What this overlay can do beyond v1, listed in its `ready`. */
+export declare const SITE_FEATURES: readonly string[];
+/** One field of a `patch`: the text being typed, and the saved value the page was rendered from. */
+export interface PatchField {
+    field: string;
+    value: string;
+    saved: string;
+}
+/** A `patch` past these is refused whole: no form has that many text fields, or that much text in one. */
+export declare const PATCH_MAX_FIELDS = 500;
+export declare const PATCH_MAX_LENGTH = 100000;
 export type AdminMessage = {
     source: typeof ADMIN_SOURCE;
     v: 1;
@@ -41,6 +71,12 @@ export type AdminMessage = {
     source: typeof ADMIN_SOURCE;
     v: 1;
     type: "refresh";
+} | {
+    source: typeof ADMIN_SOURCE;
+    v: 1;
+    type: "patch";
+    entryId: string;
+    fields: PatchField[];
 };
 export type SiteMessage = {
     source: typeof SITE_SOURCE;
@@ -48,6 +84,7 @@ export type SiteMessage = {
     type: "ready";
     path: string;
     entries: string[];
+    features?: string[];
 } | {
     source: typeof SITE_SOURCE;
     v: 1;
@@ -60,6 +97,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 {
@@ -86,6 +129,59 @@ export declare function normaliseOrigins(origins: readonly string[]): string[];
  * `allowedOrigins` is expected already normalised (`normaliseOrigins`).
  */
 export declare function acceptMessage(event: MessageLike, allowedOrigins: readonly string[], parent: unknown): AdminMessage | null;
-export declare function readyMessage(path: string, entries: string[]): SiteMessage;
+/**
+ * The text a node should read after a patch, or null to leave it alone.
+ *
+ * Only while its text (trimmed) is the saved value or what this page last
+ * patched it to, so text the site formats is never touched. The whitespace a
+ * template put around it stays. Null too when there is nothing to change.
+ */
+export declare function patchedText(current: string, change: {
+    value: string;
+    saved: string;
+}, lastPatched: string | null, around?: {
+    lead: string;
+    trail: string;
+}): string | null;
+/**
+ * The whitespace around a node's text, which a patch keeps. A node that is
+ * only whitespace keeps it in front. The overlay remembers this from the
+ * first patch, so text typed away to nothing and back lands where it was.
+ */
+export declare function textAround(current: string): {
+    lead: string;
+    trail: string;
+};
+export declare function readyMessage(path: string, entries: string[], features?: readonly 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

@@ -11,25 +11,54 @@
  *     highlight { entryId, field: string | null }    entryId "" clears
  *     outline   { on: boolean }                      outline every tagged element
  *     refresh   {}                                   re-render the draft
+ *     patch     { entryId, fields: [{ field, value, saved }] }
+ *                                                    unsaved text, as the editor types it
  *
  *   site -> admin  (source "capa")
- *     ready     { path, entries }                    after hello, and after every navigation
+ *     ready     { path, entries, features }          after hello, and after every navigation.
+ *                                                    `features`: what this overlay can do
+ *                                                    beyond v1 (`SITE_FEATURES`)
  *     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. `patch` and `features` are the
+ * same kind of addition: an admin sends `patch` only to an overlay whose
+ * `ready` lists "patch", and an older admin never reads `features`.
+ *
+ * A PATCH IS TEXT ONLY, and only where the page shows the field verbatim. The
+ * overlay changes a tagged element's text while it reads exactly `saved` (the
+ * value the page was rendered from) or what this page last patched it to, so
+ * a field the site formats (a price, a date, Markdown) is left alone until the
+ * save re-renders it (`patchedText`).
  *
  * The admin keeps its own copy of these shapes (`apps/admin`, no dependency on
  * this package). If you change one side, change the other.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SITE_SOURCE = exports.ADMIN_SOURCE = exports.PROTOCOL_VERSION = void 0;
+exports.PATCH_MAX_LENGTH = exports.PATCH_MAX_FIELDS = exports.SITE_FEATURES = exports.SITE_SOURCE = exports.ADMIN_SOURCE = exports.PROTOCOL_VERSION = void 0;
 exports.normaliseOrigins = normaliseOrigins;
 exports.acceptMessage = acceptMessage;
+exports.patchedText = patchedText;
+exports.textAround = textAround;
 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";
+/** What this overlay can do beyond v1, listed in its `ready`. */
+exports.SITE_FEATURES = ["patch"];
+/** A `patch` past these is refused whole: no form has that many text fields, or that much text in one. */
+exports.PATCH_MAX_FIELDS = 500;
+exports.PATCH_MAX_LENGTH = 100_000;
 /**
  * `https://admin.example.com/` and `https://admin.example.com` are one origin,
  * and a configured value that is not a URL at all is dropped rather than
@@ -89,12 +118,62 @@ function acceptMessage(event, allowedOrigins, parent) {
             if (m.field !== null && typeof m.field !== "string")
                 return null;
             return { source: exports.ADMIN_SOURCE, v: 1, type: "highlight", entryId: m.entryId, field: m.field };
+        case "patch": {
+            if (typeof m.entryId !== "string" || m.entryId === "")
+                return null;
+            if (!Array.isArray(m.fields) || m.fields.length > exports.PATCH_MAX_FIELDS)
+                return null;
+            const fields = [];
+            for (const raw of m.fields) {
+                if (typeof raw !== "object" || raw === null)
+                    return null;
+                const f = raw;
+                if (typeof f.field !== "string" || f.field === "")
+                    return null;
+                if (typeof f.value !== "string" || typeof f.saved !== "string")
+                    return null;
+                if (f.value.length > exports.PATCH_MAX_LENGTH || f.saved.length > exports.PATCH_MAX_LENGTH)
+                    return null;
+                fields.push({ field: f.field, value: f.value, saved: f.saved });
+            }
+            return { source: exports.ADMIN_SOURCE, v: 1, type: "patch", entryId: m.entryId, fields };
+        }
         default:
             return null;
     }
 }
-function readyMessage(path, entries) {
-    return { source: exports.SITE_SOURCE, v: 1, type: "ready", path, entries };
+/**
+ * The text a node should read after a patch, or null to leave it alone.
+ *
+ * Only while its text (trimmed) is the saved value or what this page last
+ * patched it to, so text the site formats is never touched. The whitespace a
+ * template put around it stays. Null too when there is nothing to change.
+ */
+function patchedText(current, change, lastPatched, around = textAround(current)) {
+    const text = current.trim();
+    const ours = text === change.saved.trim() || (lastPatched !== null && text === lastPatched.trim());
+    if (!ours || text === change.value.trim())
+        return null;
+    return `${around.lead}${change.value}${around.trail}`;
+}
+/**
+ * The whitespace around a node's text, which a patch keeps. A node that is
+ * only whitespace keeps it in front. The overlay remembers this from the
+ * first patch, so text typed away to nothing and back lands where it was.
+ */
+function textAround(current) {
+    const text = current.trim();
+    if (text === "")
+        return { lead: current, trail: "" };
+    return {
+        lead: current.slice(0, current.length - current.trimStart().length),
+        trail: current.slice(current.trimEnd().length),
+    };
+}
+function readyMessage(path, entries, features) {
+    return features
+        ? { source: exports.SITE_SOURCE, v: 1, type: "ready", path, entries, features: [...features] }
+        : { source: exports.SITE_SOURCE, v: 1, type: "ready", path, entries };
 }
 function selectMessage(entryId, field) {
     return { source: exports.SITE_SOURCE, v: 1, type: "select", entryId, field };
@@ -104,3 +183,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,16 +1,9 @@
 {
   "name": "@capacms/sdk",
-  "version": "1.0.0-next.1",
+  "version": "1.0.0-next.10",
+  "description": "The TypeScript SDK for Capa's content API: REST and GraphQL reads typed from your models, Next.js caching and live preview, and codegen.",
   "license": "UNLICENSED",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ZVN-DEV/capa-cms-future.git",
-    "directory": "packages/sdk"
-  },
-  "homepage": "https://github.com/ZVN-DEV/capa-cms-future/tree/main/packages/sdk#readme",
-  "bugs": {
-    "url": "https://github.com/ZVN-DEV/capa-cms-future/issues"
-  },
+  "homepage": "https://docs.capacms.com/api",
   "engines": {
     "node": ">=18"
   },
@@ -18,7 +11,8 @@
   "files": [
     "dist",
     "bin",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public",
@@ -39,11 +33,39 @@
       "types": "./dist/nextjs/index.d.ts",
       "default": "./dist/nextjs/index.js"
     },
+    "./image": {
+      "import": {
+        "types": "./dist/esm/image/index.d.ts",
+        "default": "./dist/esm/image/index.js"
+      },
+      "types": "./dist/image/index.d.ts",
+      "default": "./dist/image/index.js"
+    },
     "./overlay": {
+      "import": {
+        "types": "./dist/esm/overlay/index.d.ts",
+        "default": "./dist/esm/overlay/index.js"
+      },
       "types": "./dist/overlay/index.d.ts",
       "default": "./dist/overlay/index.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./nextjs/overlay": {
+      "import": {
+        "types": "./dist/esm/nextjs/overlay.d.ts",
+        "default": "./dist/esm/nextjs/overlay.js"
+      },
+      "types": "./dist/nextjs/overlay.d.ts",
+      "default": "./dist/nextjs/overlay.js"
+    },
+    "./nextjs/image-loader": {
+      "import": {
+        "types": "./dist/esm/nextjs/image-loader.d.ts",
+        "default": "./dist/esm/nextjs/image-loader.js"
+      },
+      "types": "./dist/nextjs/image-loader.d.ts",
+      "default": "./dist/nextjs/image-loader.js"
+    }
   },
   "typesVersions": {
     "*": {
@@ -56,21 +78,47 @@
       "overlay": [
         "dist/overlay/index.d.ts"
       ],
+      "nextjs/overlay": [
+        "dist/nextjs/overlay.d.ts"
+      ],
+      "nextjs/image-loader": [
+        "dist/nextjs/image-loader.d.ts"
+      ],
+      "image": [
+        "dist/image/index.d.ts"
+      ],
       "*": [
         "dist/index.d.ts"
       ]
     }
   },
   "bin": {
+    "capa": "bin/capa.js",
     "capa-codegen": "bin/capa-codegen.js"
   },
+  "peerDependencies": {
+    "graphql": "^16.9.0",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "graphql": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "graphql": "^16.9.0",
     "typescript": "^5.5.0",
+    "@types/react": "19.0.1",
+    "next": "15.5.9",
+    "react": "19.2.8",
     "@capa/shared": "0.1.0"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "tsc -p tsconfig.json && node --test test/codegen.test.js test/client.test.js test/next-client.test.js test/nextjs.test.js test/webhooks.test.js test/attrs.test.js test/overlay.test.js && tsc -p test/types/tsconfig.consumer.json --noEmit"
+    "build": "node scripts/shared-image.js && tsc -p tsconfig.json && tsc -p tsconfig.esm.json && node scripts/esm-scope.js",
+    "typecheck": "node scripts/shared-image.js && tsc -p tsconfig.json --noEmit && tsc -p tsconfig.esm.json --noEmit",
+    "test": "pnpm run build && node --test test/comments.test.js test/codegen.test.js test/client.test.js test/next-client.test.js test/nextjs.test.js test/webhooks.test.js test/attrs.test.js test/overlay.test.js test/overlay-dom.test.js test/nextjs-overlay-refresh.test.js test/nextjs-overlay-bundle.test.js test/inflate.test.js test/field-names.test.js test/next-graphql.test.js test/graphql-codegen.test.js test/graphql-contract.test.js test/readme-snippets.test.js test/nextjs-app.test.js test/nextjs-preview-app.test.js test/package-json.test.js test/changelog.test.js test/published-docs.test.js test/builder-messages.test.js test/image.test.js test/nextjs-image-loader.test.js test/capa-cli-handoff.test.js && tsc -p test/types/tsconfig.consumer.json --noEmit && tsc -p test/types/tsconfig.nonstrict.json --noEmit && tsc -p test/types/tsconfig.next.json --noEmit"
   }
 }