canopycms-next 0.0.68-int.94 → 0.0.68-int.96

package/dist/client.d.ts

@@ -29,11 +29,16 @@ export declare const NextCanopyEditorPage: (config: CanopyClientConfig, customRe
 /** 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> {
+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`;
@@ -48,4 +53,6 @@ export interface CanopyPreviewProps<T> {
  * 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>(View: (props: CanopyPreviewViewProps<T>) => ReactNode): (props: CanopyPreviewProps<T>) => ReactElement;
+export declare function withCanopyPreview<T, X = undefined>(View: (props: CanopyPreviewViewProps<T> & {
+    extras: X | undefined;
+}) => ReactNode): (props: CanopyPreviewProps<T, X>) => ReactElement;

package/dist/client.js

@@ -58,8 +58,10 @@ export const NextCanopyEditorPage = (config, customRenderers) => {
  * which JSX accepts on every supported TypeScript, where `ReactNode` needs `JSX.ElementType`.
  */
 export function withCanopyPreview(View) {
-    return function CanopyPreview({ initialData, editorOrigin }) {
+    return function CanopyPreview({ initialData, editorOrigin, extras }) {
         const preview = useCanopyPreview({ initialData, editorOrigin });
-        return _jsx(View, { ...preview });
+        // `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/context-wrapper.d.ts

@@ -146,6 +146,8 @@ export interface NextCanopyContextResult {
      * 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 */

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { createCanopyCatchAllHandler, wrapNextRequest, type CanopyNextOptions } from './adapter.js';
 export { createNextCanopyContext, type NextCanopyOptions, type NextCanopyContextResult, } from './context-wrapper.js';
-export type { CreatePreviewPageOptions, PreviewPageProps } from './preview-page.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

@@ -2,13 +2,67 @@ 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. An entry whose type
-     * has no view is a 404.
+     * `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, (props: CanopyPreviewProps<never>) => ReactNode>;
+    views: Record<string, PreviewView | ErasedPreviewViewWithLoader>;
     /** Editor origin to trust, for an editor on another origin. Defaults to the page's own. */
     editorOrigin?: string;
 }
@@ -33,3 +87,4 @@ export interface PreviewPageProps {
  * @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

@@ -1,5 +1,18 @@
 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.
@@ -26,11 +39,26 @@ export function createPreviewPageFor(getCanopy, options, deployedAs = 'server')
         if (!result)
             notFound();
         const { entryType } = result.meta;
-        const View = Object.prototype.hasOwnProperty.call(options.views, entryType)
+        const viewEntry = Object.prototype.hasOwnProperty.call(options.views, entryType)
             ? options.views[entryType]
             : undefined;
-        if (!View)
+        if (!viewEntry)
             notFound();
-        return _jsx(View, { initialData: result.data, editorOrigin: options.editorOrigin });
+        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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canopycms-next",
-  "version": "0.0.68-int.94",
+  "version": "0.0.68-int.96",
   "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.94"
+    "canopycms": "0.0.68-int.96"
   },
   "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.94"
+    "canopycms": "0.0.68-int.96"
   },
   "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",