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

package/dist/nextjs/overlay.d.ts

@@ -0,0 +1,30 @@
+export interface CapaOverlayProps {
+    /** The Capa admin origins allowed to drive the overlay. */
+    adminOrigins: string[];
+    /**
+     * How a save shows. `"in-place"` (the default) re-renders the draft with
+     * `router.refresh()`, and reloads the page only if that has not landed
+     * within `refreshTimeoutMs`. `"reload"` reloads the page on every save.
+     * The scroll position is kept either way.
+     */
+    refresh?: "in-place" | "reload";
+    /** How long an in-place refresh may take before the page reloads instead. 10 seconds. */
+    refreshTimeoutMs?: number;
+}
+/**
+ * The refresh runs in a transition, so `isPending` says when the new draft
+ * has been committed to the screen, and the overlay settles the refresh
+ * then: it puts the scroll position back, and a refresh that has not
+ * committed within `refreshTimeoutMs` reloads.
+ *
+ * While the transition is pending the overlay makes a no-op state update
+ * every `REFRESH_NUDGE_MS`. React 19.2 under Next 15.5 can leave a draft
+ * refresh suspended after every part of its streamed response has arrived:
+ * the page suspends inside an already visible Suspense boundary (a root
+ * `loading.tsx` makes one around every page), and the signal that its data
+ * is ready is lost, so nothing commits until some other state update. Any
+ * state update makes React retry the suspended render, which then completes.
+ * A refresh that commits on its own stops the nudges at once. Draft mode
+ * only: a visitor never runs this component.
+ */
+export declare function CapaOverlay({ adminOrigins, refresh, refreshTimeoutMs }: CapaOverlayProps): null;

package/dist/nextjs/overlay.js

@@ -0,0 +1,78 @@
+"use strict";
+"use client";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CapaOverlay = CapaOverlay;
+/**
+ * `<CapaOverlay />`: Capa's live preview overlay as one Next.js client
+ * component (M6).
+ *
+ *   // app/layout.tsx (a server component)
+ *   import { CapaOverlay } from "@capacms/sdk/nextjs/overlay";
+ *   {edit ? <CapaOverlay adminOrigins={["https://app.capacms.com"]} /> : null}
+ *
+ * Render it only in edit mode (`editMode()` from `@capacms/sdk/nextjs`), so a
+ * visitor never downloads it. Inside the Capa editor it outlines the focused
+ * field, reports clicks back, and on a save re-renders the page with
+ * `router.refresh()`, keeping the scroll position. Outside a Capa frame it does
+ * nothing at all.
+ *
+ * Its own entry point, apart from `@capacms/sdk/nextjs`, because it imports
+ * `react` and `next/navigation` and is a client module: the server helpers must
+ * stay free of both. A bundler that imports it gets an ES module, so it sees
+ * that only `useRouter` is used from `next/navigation` and leaves the chunks a
+ * visitor loads as they were.
+ */
+const react_1 = require("react");
+const navigation_1 = require("next/navigation");
+const index_js_1 = require("../overlay/index.js");
+/**
+ * While a refresh is pending, the overlay updates its own unused state this
+ * often. See `CapaOverlay` for why.
+ */
+const REFRESH_NUDGE_MS = 300;
+/**
+ * The refresh runs in a transition, so `isPending` says when the new draft
+ * has been committed to the screen, and the overlay settles the refresh
+ * then: it puts the scroll position back, and a refresh that has not
+ * committed within `refreshTimeoutMs` reloads.
+ *
+ * While the transition is pending the overlay makes a no-op state update
+ * every `REFRESH_NUDGE_MS`. React 19.2 under Next 15.5 can leave a draft
+ * refresh suspended after every part of its streamed response has arrived:
+ * the page suspends inside an already visible Suspense boundary (a root
+ * `loading.tsx` makes one around every page), and the signal that its data
+ * is ready is lost, so nothing commits until some other state update. Any
+ * state update makes React retry the suspended render, which then completes.
+ * A refresh that commits on its own stops the nudges at once. Draft mode
+ * only: a visitor never runs this component.
+ */
+function CapaOverlay({ adminOrigins, refresh = "in-place", refreshTimeoutMs }) {
+    const router = (0, navigation_1.useRouter)();
+    const [refreshing, startRefresh] = (0, react_1.useTransition)();
+    const [, nudge] = (0, react_1.useState)(0);
+    /** One resolver per refresh waiting for its transition to commit. */
+    const waiting = (0, react_1.useRef)([]);
+    // A string, so a new array with the same origins does not restart it.
+    const origins = adminOrigins.join(",");
+    (0, react_1.useEffect)(() => (0, index_js_1.startOverlay)({
+        adminOrigins: origins.split(",").filter(Boolean),
+        onRefresh: refresh === "reload"
+            ? undefined
+            : () => new Promise((resolve) => {
+                waiting.current.push(resolve);
+                startRefresh(() => router.refresh());
+            }),
+        refreshTimeoutMs,
+    }), [origins, router, refresh, refreshTimeoutMs]);
+    (0, react_1.useEffect)(() => {
+        if (!refreshing) {
+            // Committed: every refresh started before now is on screen.
+            for (const settle of waiting.current.splice(0))
+                settle();
+            return;
+        }
+        const timer = window.setInterval(() => nudge((n) => n + 1), REFRESH_NUDGE_MS);
+        return () => window.clearInterval(timer);
+    }, [refreshing]);
+    return null;
+}

package/dist/overlay/index.d.ts

@@ -0,0 +1,32 @@
+export { acceptMessage, hoverMessage, normaliseOrigins, patchedText, pickCentred, readyMessage, scrollEdge, selectMessage, textAround, visibleMessage, ADMIN_SOURCE, PATCH_MAX_FIELDS, PATCH_MAX_LENGTH, PROTOCOL_VERSION, SITE_FEATURES, SITE_SOURCE, } from "./protocol.js";
+export type { AdminMessage, MessageLike, PatchField, SiteMessage, TaggedBox } from "./protocol.js";
+export interface OverlayOptions {
+    /**
+     * The Capa admin origins allowed to drive this page, for example
+     * `["https://app.capacms.com"]`. A message from anywhere else is ignored.
+     */
+    adminOrigins: string[];
+    /**
+     * How to re-render the draft after the editor saves. `router.refresh()` in a
+     * Next app. Without it the page reloads. Scroll position is kept either way.
+     *
+     * Return a promise that settles once the new draft is on screen, and the
+     * overlay waits for it: a promise that rejects, or is still pending after
+     * `refreshTimeoutMs`, falls back to a reload, which keeps the scroll
+     * position too. A function that returns nothing counts as done at once.
+     */
+    onRefresh?: () => void | Promise<void>;
+    /**
+     * How long `onRefresh`'s promise may stay pending before the page reloads
+     * instead. 10 seconds.
+     */
+    refreshTimeoutMs?: number;
+}
+/** How long an in-place refresh may take before the page reloads instead. */
+export declare const REFRESH_TIMEOUT_MS = 10000;
+/**
+ * Start the overlay. Returns a disposer that removes every listener and the
+ * drawing layer. Calling it again while it runs updates the options and returns
+ * the same disposer, so a React effect that runs twice does not listen twice.
+ */
+export declare function startOverlay(options: OverlayOptions): () => void;