canopycms-next 0.0.68-int.93 → 0.0.68-int.95

package/dist/client.d.ts

@@ -1,3 +1,5 @@
+import { type ReactElement, type ReactNode } from 'react';
+import { useCanopyPreview } from 'canopycms/client';
 import type { CanopyClientConfig, CustomFieldRenderers } from 'canopycms/client';
 /**
  * Next.js-specific wrapper for CanopyEditorPage that automatically reads
@@ -24,3 +26,33 @@ import type { CanopyClientConfig, CustomFieldRenderers } from 'canopycms/client'
  * ```
  */
 export declare const NextCanopyEditorPage: (config: CanopyClientConfig, customRenderers?: CustomFieldRenderers) => () => import("react/jsx-runtime").JSX.Element;
+/** What a preview view renders from: the editor's live draft, plus `useCanopyPreview`'s helpers. */
+export type CanopyPreviewViewProps<T> = ReturnType<typeof useCanopyPreview<T>>;
+/** The props of a view wrapped by `withCanopyPreview`. */
+export interface CanopyPreviewProps<T, X = undefined> {
+    /** The saved entry data, rendered until the editor sends a draft. */
+    initialData: T;
+    /** Editor origin to trust, for an editor on another origin. Defaults to this page's own. */
+    editorOrigin?: string;
+    /**
+     * What the route's `load` returned (see `previewView`), handed to the view untouched as its
+     * `extras` prop. Absent on a public page and for a view with no loader.
+     */
+    extras?: X;
+}
+/**
+ * Wraps a view so it renders the editor's live draft of `initialData`, through `useCanopyPreview`;
+ * outside an editor frame it renders `initialData` unchanged.
+ *
+ * Call it in your own `'use client'` module and pass the result to `createPreviewPage`'s `views`,
+ * or render it on a public page. The wrapping lives in your module, not in `createPreviewPage`,
+ * because Next ships every client module a page's server code imports: one imported by the
+ * context would put the editor in every page that reads content.
+ *
+ * The returned type is a call signature rather than `ComponentType`, whose `propTypes` would make
+ * a view for one content type unassignable to a map of views for many. It returns `ReactElement`,
+ * which JSX accepts on every supported TypeScript, where `ReactNode` needs `JSX.ElementType`.
+ */
+export declare function withCanopyPreview<T, X = undefined>(View: (props: CanopyPreviewViewProps<T> & {
+    extras: X | undefined;
+}) => ReactNode): (props: CanopyPreviewProps<T, X>) => ReactElement;

package/dist/client.js

@@ -2,7 +2,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Suspense } from 'react';
 import { useSearchParams } from 'next/navigation';
-import { CanopyEditorPage } from 'canopycms/client';
+import { CanopyEditorPage, useCanopyPreview } from 'canopycms/client';
 /**
  * Next.js-specific wrapper for CanopyEditorPage that automatically reads
  * URL search params (branch, entry) using Next.js's useSearchParams hook.
@@ -44,3 +44,24 @@ export const NextCanopyEditorPage = (config, customRenderers) => {
         return (_jsx(Suspense, { fallback: null, children: _jsx(EditorWithSearchParams, {}) }));
     };
 };
+/**
+ * Wraps a view so it renders the editor's live draft of `initialData`, through `useCanopyPreview`;
+ * outside an editor frame it renders `initialData` unchanged.
+ *
+ * Call it in your own `'use client'` module and pass the result to `createPreviewPage`'s `views`,
+ * or render it on a public page. The wrapping lives in your module, not in `createPreviewPage`,
+ * because Next ships every client module a page's server code imports: one imported by the
+ * context would put the editor in every page that reads content.
+ *
+ * The returned type is a call signature rather than `ComponentType`, whose `propTypes` would make
+ * a view for one content type unassignable to a map of views for many. It returns `ReactElement`,
+ * which JSX accepts on every supported TypeScript, where `ReactNode` needs `JSX.ElementType`.
+ */
+export function withCanopyPreview(View) {
+    return function CanopyPreview({ initialData, editorOrigin, extras }) {
+        const preview = useCanopyPreview({ initialData, editorOrigin });
+        // `extras` is a prop of its own, never spread into the hook's result, so it cannot shadow
+        // `data` or `fieldProps`.
+        return _jsx(View, { ...preview, extras: extras });
+    };
+}

package/dist/config.cjs

@@ -399,7 +399,7 @@ function withCanopy(nextConfig = {}, options = {}) {
     ])
   ];
   const generateBuildId = nextConfig.generateBuildId ?? (options.staticBuild ? resolveStaticBuildId : void 0);
-  const env = nextConfig.trailingSlash ? { CANOPY_API_TRAILING_SLASH: "true", ...nextConfig.env } : void 0;
+  const env = nextConfig.trailingSlash ? { CANOPY_TRAILING_SLASH: "true", ...nextConfig.env } : void 0;
   return {
     ...nextConfig,
     transpilePackages: allPackages,

package/dist/config.mjs

@@ -363,7 +363,7 @@ function withCanopy(nextConfig = {}, options = {}) {
     ])
   ];
   const generateBuildId = nextConfig.generateBuildId ?? (options.staticBuild ? resolveStaticBuildId : void 0);
-  const env = nextConfig.trailingSlash ? { CANOPY_API_TRAILING_SLASH: "true", ...nextConfig.env } : void 0;
+  const env = nextConfig.trailingSlash ? { CANOPY_TRAILING_SLASH: "true", ...nextConfig.env } : void 0;
   return {
     ...nextConfig,
     transpilePackages: allPackages,

package/dist/context-wrapper.d.ts

@@ -1,7 +1,9 @@
 import { type CanopyContext, type CanopyBuildContext, type CanopyServices, type SeoFieldLocation } from 'canopycms/server';
 import type { CanopyConfig, AuthPlugin, FieldConfig } from 'canopycms';
 import type { Metadata, MetadataRoute } from 'next';
+import type { ReactElement } from 'react';
 import { createCanopyCatchAllHandler } from './adapter.js';
+import { type CreatePreviewPageOptions, type PreviewPageProps } from './preview-page.js';
 import { type EntryToMetadataOptions, type GenerateContentSitemapOptions, type GenerateContentStaticParamsOptions } from './static.js';
 /**
  * Merge a context-wide default SEO field location (`createNextCanopyContext({ seo })`) with a
@@ -132,6 +134,22 @@ export interface NextCanopyContextResult {
      * (see that function's doc); pass `fields`/`group` on a given call to override just that call.
      */
     entryToMetadata: (entryData: unknown, options?: EntryToMetadataOptions) => Metadata;
+    /**
+     * The page for the preview route the editor's `previewPrefix` names, for a site whose public
+     * pages are a static export. Mount it as `app/<prefix>/[[...path]]/page.server.tsx`, so only the
+     * CMS build has it:
+     *
+     * ```tsx
+     * export default createPreviewPage({ views: { post: PostPreview, doc: DocPreview } })
+     * ```
+     *
+     * Each view is made by `withCanopyPreview` (`canopycms-next/client`) in a `'use client'` module.
+     * It renders each entry from the `?branch=` the editor names, through `views[entryType]` with
+     * the live draft. Reads are request-scoped and ACL-checked, and anything not readable is a 404.
+     * A view that needs more server reads is `previewView({ view, load })`: `load` runs after the
+     * entry is read and its result arrives as the view's `extras` prop.
+     */
+    createPreviewPage: (options: CreatePreviewPageOptions) => (props: PreviewPageProps) => Promise<ReactElement>;
     /** API catch-all route handler */
     handler: ReturnType<typeof createCanopyCatchAllHandler>;
     /** Underlying services (rarely needed directly) */

package/dist/context-wrapper.js

@@ -5,6 +5,7 @@ import { createCanopyContext, isBuildMode, startDevContentWatcher, createCanopyS
 import { assertAuthPluginAllowedForMode } from 'canopycms/auth';
 import { CachingAuthPlugin, FileBasedAuthCache } from 'canopycms/auth/cache';
 import { createCanopyCatchAllHandler } from './adapter.js';
+import { createPreviewPageFor, } from './preview-page.js';
 import { collectStaticParams, entryToMetadata as entryToMetadataCore, generateContentSitemap, } from './static.js';
 /**
  * Merge a context-wide default SEO field location (`createNextCanopyContext({ seo })`) with a
@@ -271,6 +272,7 @@ export async function createNextCanopyContext(options) {
         generateContentStaticParams,
         generateContentSitemap: boundGenerateContentSitemap,
         entryToMetadata: boundEntryToMetadata,
+        createPreviewPage: (previewOptions) => createPreviewPageFor(getCanopy, previewOptions, options.config.deployedAs),
         handler,
         services,
     };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { createCanopyCatchAllHandler, wrapNextRequest, type CanopyNextOptions } from './adapter.js';
 export { createNextCanopyContext, type NextCanopyOptions, type NextCanopyContextResult, } from './context-wrapper.js';
+export { previewView, type CreatePreviewPageOptions, type PreviewEntry, type PreviewLoadContext, type PreviewPageProps, type PreviewViewWithLoader, } from './preview-page.js';
 export { collectStaticParams, generateContentSitemap, entryToMetadata, type GenerateContentStaticParamsOptions, type GenerateContentSitemapOptions, type EntryToMetadataOptions, type SitemapExtraUrl, } from './static.js';
 export { createMockAuthPlugin, createRejectingAuthPlugin } from './test-utils.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { createCanopyCatchAllHandler, wrapNextRequest } from './adapter.js';
 export { createNextCanopyContext, } from './context-wrapper.js';
+export { previewView, } from './preview-page.js';
 export { collectStaticParams, generateContentSitemap, entryToMetadata, } from './static.js';
 export { createMockAuthPlugin, createRejectingAuthPlugin } from './test-utils.js';

package/dist/preview-page.d.ts

@@ -0,0 +1,90 @@
+import type { ReactElement, ReactNode } from 'react';
+import type { CanopyConfig } from 'canopycms';
+import type { CanopyContext } from 'canopycms/server';
+import type { CanopyPreviewProps } from './client.js';
+type ReadEntry = NonNullable<Awaited<ReturnType<CanopyContext['readByUrlPath']>>>;
+/**
+ * The entry a `load` receives. It carries no `meta.physicalPath`, so a loader that returns its
+ * whole `entry` cannot send the server's filesystem layout to the browser.
+ */
+export interface PreviewEntry {
+    data: unknown;
+    path: string;
+    entryType: string;
+    entryId?: ReadEntry['meta']['entryId'];
+}
+/** What a `load` receives. */
+export interface PreviewLoadContext {
+    /** The entry the route is rendering, as read from the requested branch. */
+    entry: PreviewEntry;
+    /** The request-scoped context the entry was read through: authenticated and ACL-checked. */
+    canopy: CanopyContext;
+    /** The `?branch=` the editor named, to pass on to further reads. */
+    branch: string | undefined;
+}
+/**
+ * A view and the server loader that feeds its `extras` prop. Make one with `previewView`.
+ *
+ * `load` runs on the server, once per request, after the entry is read and its view found, so an
+ * entry type with no view is a 404 without running it. It may throw, or call `notFound()`: either
+ * rejects the page rather than rendering.
+ *
+ * Its result reaches the browser like any RSC prop, so it must be RSC-serializable: plain data
+ * or React elements. A server-rendered element such as `<RelatedPosts />` is fine, which lets a
+ * view reuse a server component for a section that need not update live. The result is a
+ * snapshot of the request and does not follow the editor's live draft; only `data` does.
+ */
+export interface PreviewViewWithLoader<X> {
+    view: (props: CanopyPreviewProps<never, X>) => ReactNode;
+    load: (ctx: PreviewLoadContext) => X | Promise<X>;
+}
+/**
+ * The form `views` holds, with `X` erased. `view` takes `extras?: never`, so a view of any `X`
+ * is assignable (its parameter is only wider), and `load` returns `unknown`, so any loader is
+ * too. That drops the check that `load`'s result is what `view` expects, which `previewView`
+ * restores where each pair is written.
+ */
+interface ErasedPreviewViewWithLoader {
+    view: (props: CanopyPreviewProps<never, never>) => ReactNode;
+    load: (ctx: PreviewLoadContext) => unknown;
+}
+type PreviewView = (props: CanopyPreviewProps<never>) => ReactNode;
+/**
+ * Pairs a view with its loader, so TypeScript checks that `load`'s result is what the view's
+ * `extras` prop expects. A record of views cannot infer a distinct `X` per key, so this identity
+ * function infers it for each entry on its own.
+ */
+export declare function previewView<X>(entry: PreviewViewWithLoader<X>): PreviewViewWithLoader<X>;
+export interface CreatePreviewPageOptions {
+    /**
+     * The view for each entry type the preview route serves, keyed by entry type name, each made by
+     * `withCanopyPreview` (`canopycms-next/client`) in a `'use client'` module, or a
+     * `previewView({ view, load })` pair when the view needs more than the entry. An entry whose
+     * type has no view is a 404.
+     */
+    views: Record<string, PreviewView | ErasedPreviewViewWithLoader>;
+    /** Editor origin to trust, for an editor on another origin. Defaults to the page's own. */
+    editorOrigin?: string;
+}
+/** The props Next passes a `[[...path]]` page. */
+export interface PreviewPageProps {
+    params: Promise<{
+        path?: string[];
+    }>;
+    searchParams: Promise<Record<string, string | string[] | undefined>>;
+}
+/**
+ * The page for a `[[...path]]` route mounted at `editor.previewPrefix`: it reads the entry at
+ * the route's path from the `?branch=` the editor names and renders its view.
+ *
+ * The read goes through the request-scoped `getCanopy()`, never the build context: it is
+ * authenticated and ACL-checked, and a branch other than the active one is only loaded, never
+ * created. A missing, unreadable or malformed branch, and a path no entry publishes, are all a
+ * 404, so a hidden branch looks the same as a missing one.
+ *
+ * On a `deployedAs: 'static'` deployment every request is a 404: reads there skip access checks,
+ * so the route would show any branch to anyone.
+ * @internal Exported for tests.
+ */
+export declare function createPreviewPageFor(getCanopy: () => Promise<CanopyContext>, options: CreatePreviewPageOptions, deployedAs?: CanopyConfig['deployedAs']): (props: PreviewPageProps) => Promise<ReactElement>;
+export {};

package/dist/preview-page.js

@@ -0,0 +1,64 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { notFound } from 'next/navigation';
+/**
+ * Pairs a view with its loader, so TypeScript checks that `load`'s result is what the view's
+ * `extras` prop expects. A record of views cannot infer a distinct `X` per key, so this identity
+ * function infers it for each entry on its own.
+ */
+export function previewView(entry) {
+    return entry;
+}
+function hasLoader(entry) {
+    return (typeof entry === 'object' &&
+        entry !== null &&
+        Object.prototype.hasOwnProperty.call(entry, 'load'));
+}
+/**
+ * The page for a `[[...path]]` route mounted at `editor.previewPrefix`: it reads the entry at
+ * the route's path from the `?branch=` the editor names and renders its view.
+ *
+ * The read goes through the request-scoped `getCanopy()`, never the build context: it is
+ * authenticated and ACL-checked, and a branch other than the active one is only loaded, never
+ * created. A missing, unreadable or malformed branch, and a path no entry publishes, are all a
+ * 404, so a hidden branch looks the same as a missing one.
+ *
+ * On a `deployedAs: 'static'` deployment every request is a 404: reads there skip access checks,
+ * so the route would show any branch to anyone.
+ * @internal Exported for tests.
+ */
+export function createPreviewPageFor(getCanopy, options, deployedAs = 'server') {
+    return async function CanopyPreviewPage({ params, searchParams }) {
+        if (deployedAs === 'static')
+            notFound();
+        const [{ path = [] }, query] = await Promise.all([params, searchParams]);
+        const branch = query.branch;
+        if (Array.isArray(branch))
+            notFound();
+        const canopy = await getCanopy();
+        const result = await canopy.readByUrlPath(`/${path.join('/')}`, { branch });
+        if (!result)
+            notFound();
+        const { entryType } = result.meta;
+        const viewEntry = Object.prototype.hasOwnProperty.call(options.views, entryType)
+            ? options.views[entryType]
+            : undefined;
+        if (!viewEntry)
+            notFound();
+        if (!hasLoader(viewEntry)) {
+            const View = viewEntry;
+            return _jsx(View, { initialData: result.data, editorOrigin: options.editorOrigin });
+        }
+        const { meta } = result;
+        const entry = {
+            data: result.data,
+            path: result.path,
+            entryType: meta.entryType,
+            entryId: meta.entryId,
+        };
+        const extras = await viewEntry.load({ entry, canopy, branch });
+        // The record erases `view` to `extras?: never`, so it cannot check `load`'s result against the
+        // view; `previewView` does, where a pair is written.
+        const View = viewEntry.view;
+        return _jsx(View, { initialData: result.data, editorOrigin: options.editorOrigin, extras: extras });
+    };
+}

package/dist/with-canopy.d.ts

@@ -40,7 +40,7 @@ export interface WithCanopyOptions {
  *   (kept under `experimental` on Next 13/14 or legacy spellings; your own includes stay), so a
  *   Turbopack `output: 'standalone'` server can load sharp — Next's tracing misses that library
  *   for sharp 0.35 (doesn't fix webpack builds); warns if the directory or version can't be found.
- * - `trailingSlash: true` sets `env.CANOPY_API_TRAILING_SLASH`, so editor API calls skip Next's 308.
+ * - `trailingSlash: true` sets `env.CANOPY_TRAILING_SLASH`, so the editor's requests skip Next's 308.
  * - On Next 16+, sets `turbopack: {}` when your config has neither `turbopack` nor `webpack` and
  *   the Next version can be read — Next 16 defaults to Turbopack and exits when a config exports
  *   `webpack` (the React aliases above add one) with no `turbopack` key; a `turbopack` you set is

package/dist/with-canopy.js

@@ -337,7 +337,7 @@ function sharpTracingConfig(nextConfig, options) {
  *   (kept under `experimental` on Next 13/14 or legacy spellings; your own includes stay), so a
  *   Turbopack `output: 'standalone'` server can load sharp — Next's tracing misses that library
  *   for sharp 0.35 (doesn't fix webpack builds); warns if the directory or version can't be found.
- * - `trailingSlash: true` sets `env.CANOPY_API_TRAILING_SLASH`, so editor API calls skip Next's 308.
+ * - `trailingSlash: true` sets `env.CANOPY_TRAILING_SLASH`, so the editor's requests skip Next's 308.
  * - On Next 16+, sets `turbopack: {}` when your config has neither `turbopack` nor `webpack` and
  *   the Next version can be read — Next 16 defaults to Turbopack and exits when a config exports
  *   `webpack` (the React aliases above add one) with no `turbopack` key; a `turbopack` you set is
@@ -449,10 +449,10 @@ export function withCanopy(nextConfig = {}, options = {}) {
     // verbatim (`next/dist/build/generate-build-id.js`) — which is what makes a hex tree hash usable
     // as a build id at all. Do not "helpfully" route this through the fallback.
     const generateBuildId = nextConfig.generateBuildId ?? (options.staticBuild ? resolveStaticBuildId : undefined);
-    // Next substitutes `env` into every bundle at build time, where the API client reads it
-    // (`readApiTrailingSlashEnv` in canopycms's `api/request-url.ts`).
+    // Next substitutes `env` into every bundle at build time, where the API client and the editor's
+    // preview URLs read it (`readTrailingSlashEnv` in canopycms's `utils/url-prefix.ts`).
     const env = nextConfig.trailingSlash
-        ? { CANOPY_API_TRAILING_SLASH: 'true', ...nextConfig.env }
+        ? { CANOPY_TRAILING_SLASH: 'true', ...nextConfig.env }
         : undefined;
     return {
         ...nextConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canopycms-next",
-  "version": "0.0.68-int.93",
+  "version": "0.0.68-int.95",
   "description": "Next.js adapter for CanopyCMS",
   "license": "MIT",
   "repository": {
@@ -38,7 +38,7 @@
   "peerDependencies": {
     "next": "^13.5.7 || ^14.2.25 || ^15.5.21 || >=16.0.0 <16.2.0 || >=16.3.0 <17.0.0",
     "react": "^18.0.0 || ^19.0.0",
-    "canopycms": "0.0.68-int.93"
+    "canopycms": "0.0.68-int.95"
   },
   "devDependencies": {
     "@types/node": "^22.9.0",
@@ -48,7 +48,7 @@
     "react": "^18.3.1",
     "typescript": "^5.6.3",
     "vitest": "^4.1.0",
-    "canopycms": "0.0.68-int.93"
+    "canopycms": "0.0.68-int.95"
   },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json && node ../../scripts/add-js-extensions.mjs dist && esbuild src/config.ts --bundle --platform=node --packages=external --external:next --format=cjs --outfile=dist/config.cjs && esbuild src/config.ts --bundle --platform=node --packages=external --external:next --format=esm --outfile=dist/config.mjs",