@easy-cms/core 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -332,6 +332,14 @@ interface GlobalHooks {
     readonly afterChange?: readonly AfterChangeHook[];
     readonly afterRead?: readonly AfterReadHook[];
 }
+/**
+ * Where a document is shown on the site, for live preview in the admin: an absolute URL or a
+ * path on the site's origin. Return `null` when the document has no page.
+ */
+type PreviewURL = (args: {
+    readonly doc: Record<string, unknown>;
+    readonly locale: AdminLocale;
+}) => string | null | undefined;
 interface VersionsConfig {
     /** Versions kept per document; older ones are deleted. Default 50. */
     readonly max?: number;
@@ -354,6 +362,8 @@ interface CollectionConfig {
      * it is published again.
      */
     readonly versions?: boolean | VersionsConfig;
+    /** Live preview: the page that shows a document, e.g. `({ doc }) => \`/posts/${doc.slug}\``. */
+    readonly preview?: PreviewURL;
     readonly access?: CollectionAccess;
     readonly hooks?: CollectionHooks;
 }
@@ -364,6 +374,8 @@ interface GlobalConfig {
     readonly drafts?: boolean;
     /** Keep a snapshot of every save. See `CollectionConfig.versions`. */
     readonly versions?: boolean | VersionsConfig;
+    /** Live preview: the page that shows the global. See `CollectionConfig.preview`. */
+    readonly preview?: PreviewURL;
     readonly access?: GlobalAccess;
     readonly hooks?: GlobalHooks;
 }
@@ -771,6 +783,17 @@ declare class EasyCMS<C extends Config = Config> {
      * a draft (publish it to put it live); access, hooks and validation run as for `update`.
      */
     restoreVersion<S extends Slug<C>>(collection: S, id: ID, versionId: ID, options?: DepthOptions): Promise<Doc<C, S>>;
+    /**
+     * Live preview: the document as it would be read if `data` were saved on top of its current
+     * state (or as a new document when `id` is `null`), with relationships populated and
+     * `afterRead` hooks applied. Nothing is written. Also returns the page URL from `preview`.
+     */
+    preview<S extends Slug<C>>(collection: S, id: ID | null, data: Record<string, unknown>, options?: DepthOptions): Promise<LivePreview<Doc<C, S>>>;
+    /** Live preview of a global. See `preview`. */
+    previewGlobal<S extends GSlug<C>>(slug: S, data: Record<string, unknown>, options?: DepthOptions): Promise<LivePreview<GDoc<C, S>>>;
+    /** Coerces preview input like a save would, keeping values that would fail validation. */
+    private previewDoc;
+    private previewURL;
     private versionTarget;
     private updateDocument;
     delete<S extends Slug<C>>(collection: S, id: ID, options?: AccessOptions): Promise<Doc<C, S>>;
@@ -839,6 +862,12 @@ declare class EasyCMS<C extends Config = Config> {
     private isTaken;
     private checkReferences;
 }
+/** A document as live preview shows it, and the page to show it on. */
+interface LivePreview<T> {
+    readonly doc: T;
+    /** From the collection's `preview` function; `null` without one. */
+    readonly url: string | null;
+}
 
 interface LoginArgs {
     readonly email: string;
@@ -1076,6 +1105,8 @@ interface AdminCollection {
     useAsTitle?: string;
     drafts: boolean;
     versions: boolean;
+    /** Has live preview (`preview` in the config). */
+    preview: boolean;
     fields: AdminField[];
     permissions: {
         read: boolean;
@@ -1089,6 +1120,8 @@ interface AdminGlobal {
     label?: Label;
     drafts: boolean;
     versions: boolean;
+    /** Has live preview (`preview` in the config). */
+    preview: boolean;
     fields: AdminField[];
     permissions: {
         read: boolean;
@@ -1129,4 +1162,4 @@ declare const BUILTIN_COLLECTIONS: readonly ["users", "media"];
 /** Checks a config and returns every problem found. An empty array means it is valid. */
 declare function validateConfig(config: Config): ConfigIssue[];
 
-export { type Access, type AccessArgs, type AccessOptions, type AdminCollection, type AdminConfig, type AdminField, type AdminGlobal, type AdminLocale, type AdminSchema, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ArrayField, Auth, type AuthConfig, type AuthUser, BUILTIN_COLLECTIONS, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type BooleanField, type BuiltinMediaCollection, type BuiltinUsersCollection, type BundleHints, CONFIG_FILE_NAMES, CSRF_COOKIE, CSRF_HEADER, type CollectionAccess, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionSlug, type Config, ConfigError, type ConfigIssue, type CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_TOKEN_EXPIRATION, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DateField, type DepthOptions, EXTENSIONS, EasyCMS, EasyCMSError, type EmailField, FIELD_TYPES, type Field, type FieldAccess, type FieldAccessFn, type FieldError, type FieldType, type FieldValidate, type FieldValidateContext, type FieldValue, type FieldsInput, type FieldsValue, type FindArgs, type FindOptions, ForbiddenError, type GlobalAccess, type GlobalConfig, type GlobalDocument, type GlobalHooks, type GlobalInput, type GlobalSlug, type GroupField, type ID, INTERNAL_COLLECTIONS, type ImageSize, type InferCollection, type InferGlobal, type JsonField, type Label, type LoadConfigOptions, type LocalStorageOptions, type Logger, type LoginArgs, MAX_DEPTH, MEDIA, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, type MediaSize, type MigrationInfo, NotFoundError, type NumberField, type Operation, type PaginatedDocs, PayloadTooLargeError, type Plugin, QueryError, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoutesConfig, SESSION_COOKIE, SchemaError, type SchemaMode, type SelectField, type SelectOption, type Session, type SlugField, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, UnauthorizedError, type UpdateInput, type UploadConfig, type UploadField, ValidationError, type Version, type VersionSummary, type VersionsConfig, type Where, type WhereOperators, anyone, applyDefaults, consoleLogger, createEasyCMS, createRestHandler, defineConfig, fillMissing, findConfigFile, generateSlugs, generateTypes, hashPassword, imageDimensions, importConfig, isAdmin, isLoggedIn, loadConfig, localStorage, mergeForUpdate, mimeAllowed, parseId, populate, readCookie, resolveConfig, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword };
+export { type Access, type AccessArgs, type AccessOptions, type AdminCollection, type AdminConfig, type AdminField, type AdminGlobal, type AdminLocale, type AdminSchema, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ArrayField, Auth, type AuthConfig, type AuthUser, BUILTIN_COLLECTIONS, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type BooleanField, type BuiltinMediaCollection, type BuiltinUsersCollection, type BundleHints, CONFIG_FILE_NAMES, CSRF_COOKIE, CSRF_HEADER, type CollectionAccess, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionSlug, type Config, ConfigError, type ConfigIssue, type CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_TOKEN_EXPIRATION, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DateField, type DepthOptions, EXTENSIONS, EasyCMS, EasyCMSError, type EmailField, FIELD_TYPES, type Field, type FieldAccess, type FieldAccessFn, type FieldError, type FieldType, type FieldValidate, type FieldValidateContext, type FieldValue, type FieldsInput, type FieldsValue, type FindArgs, type FindOptions, ForbiddenError, type GlobalAccess, type GlobalConfig, type GlobalDocument, type GlobalHooks, type GlobalInput, type GlobalSlug, type GroupField, type ID, INTERNAL_COLLECTIONS, type ImageSize, type InferCollection, type InferGlobal, type JsonField, type Label, type LivePreview, type LoadConfigOptions, type LocalStorageOptions, type Logger, type LoginArgs, MAX_DEPTH, MEDIA, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, type MediaSize, type MigrationInfo, NotFoundError, type NumberField, type Operation, type PaginatedDocs, PayloadTooLargeError, type Plugin, type PreviewURL, QueryError, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoutesConfig, SESSION_COOKIE, SchemaError, type SchemaMode, type SelectField, type SelectOption, type Session, type SlugField, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, UnauthorizedError, type UpdateInput, type UploadConfig, type UploadField, ValidationError, type Version, type VersionSummary, type VersionsConfig, type Where, type WhereOperators, anyone, applyDefaults, consoleLogger, createEasyCMS, createRestHandler, defineConfig, fillMissing, findConfigFile, generateSlugs, generateTypes, hashPassword, imageDimensions, importConfig, isAdmin, isLoggedIn, loadConfig, localStorage, mergeForUpdate, mimeAllowed, parseId, populate, readCookie, resolveConfig, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword };

package/dist/index.js

@@ -1032,6 +1032,13 @@ function validateContainer(container, path, collectionSlugs, add) {
       add(`${path}.versions.max`, "must be a positive integer");
     }
   }
+  if (container.preview !== void 0 && typeof container.preview !== "function") {
+    add(
+      `${path}.preview`,
+      "must be a function ({ doc }) => url",
+      "preview: ({ doc }) => `/posts/${doc.slug}`"
+    );
+  }
   const reserved = new Set(SYSTEM_FIELD_NAMES);
   if (container.drafts) reserved.add("status");
   validateFields2(container.fields, `${path}.fields`, reserved, collectionSlugs, add);
@@ -1825,6 +1832,91 @@ var EasyCMS = class {
       options
     );
   }
+  /**
+   * Live preview: the document as it would be read if `data` were saved on top of its current
+   * state (or as a new document when `id` is `null`), with relationships populated and
+   * `afterRead` hooks applied. Nothing is written. Also returns the page URL from `preview`.
+   */
+  async preview(collection2, id, data, options = {}) {
+    const config = this.collection(collection2);
+    const guard = guardOf(options);
+    const raw = asObject(data, collection2);
+    let base;
+    let parsed;
+    if (id === null) {
+      if (guard.enforce) {
+        const allowed2 = await evaluateAccess(config.access?.create, { user: guard.user, data: raw });
+        if (allowed2 !== true) throw deny(guard.user);
+      }
+    } else {
+      parsed = parseId(id);
+      const existing = parsed === void 0 ? null : await this.db.findById({ collection: collection2, id: parsed });
+      if (!existing || parsed === void 0) throw new NotFoundError(collection2, id);
+      await this.checkDocumentAccess(config, "update", guard, parsed, raw);
+      [base] = await this.withDrafts(config, [existing]);
+    }
+    const { input } = splitPassword(config, raw);
+    const filtered = await filterInput(
+      config.fields,
+      input,
+      this.fieldChecker("update", guard, parsed, input)
+    );
+    const merged = base ? mergeForUpdate(config.fields, base, filtered) : applyDefaults(config.fields, filtered);
+    if (config.drafts) merged.status = filtered.status ?? base?.status ?? "draft";
+    const doc = await this.previewDoc(config, generateSlugs(config.fields, merged), {
+      id: parsed ?? 0,
+      createdAt: base?.createdAt ?? (/* @__PURE__ */ new Date()).toISOString()
+    });
+    const [out] = await this.output(config, [doc], guard, { ...options, draft: true });
+    return { doc: out, url: this.previewURL(config, out) };
+  }
+  /** Live preview of a global. See `preview`. */
+  async previewGlobal(slug, data, options = {}) {
+    const config = this.global(slug);
+    const guard = guardOf(options);
+    await this.checkGlobalAccess(config, "update", guard);
+    const raw = asObject(data, slug);
+    const input = await filterInput(
+      config.fields,
+      raw,
+      this.fieldChecker("update", guard, void 0, raw)
+    );
+    const saved = await this.db.findGlobal({ slug }) ?? {};
+    const current = await this.globalDraft(config, saved);
+    const merged = generateSlugs(
+      config.fields,
+      applyDefaults(config.fields, mergeForUpdate(config.fields, current, input))
+    );
+    if (config.drafts) merged.status = input.status ?? current.status ?? "draft";
+    const doc = await this.previewDoc(config, merged, { id: 0 });
+    const [out] = await this.output(config, [doc], guard, { ...options, draft: true });
+    const { id: _id, ...global2 } = out;
+    return { doc: global2, url: this.previewURL(config, global2) };
+  }
+  /** Coerces preview input like a save would, keeping values that would fail validation. */
+  async previewDoc(config, data, system) {
+    const { data: clean } = await validateFields(config.fields, data, {
+      operation: "update",
+      root: data,
+      skipRequired: true
+    });
+    return {
+      ...data,
+      ...clean,
+      ...config.drafts ? { status: data.status } : {},
+      ...system,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  previewURL(config, doc) {
+    if (!config.preview) return null;
+    try {
+      return config.preview({ doc, locale: this.config.admin.locale }) ?? null;
+    } catch (error) {
+      this.logger.error(`preview URL of "${config.slug}" failed: ${error.message}`);
+      return null;
+    }
+  }
   async versionTarget(collection2, id, options) {
     const config = this.collection(collection2);
     if (!versionLimit(config)) throw new QueryError(`"${collection2}" has no versions`);
@@ -2499,6 +2591,7 @@ async function collection(config, user) {
     slug: config.slug,
     drafts: config.drafts === true,
     versions: Boolean(config.versions),
+    preview: typeof config.preview === "function",
     fields: await serializeFields(config.fields, new FieldAccessChecker("update", { user })),
     permissions: {
       read: await allowed(config.access?.read, user),
@@ -2516,6 +2609,7 @@ async function global(config, user) {
     slug: config.slug,
     drafts: config.drafts === true,
     versions: Boolean(config.versions),
+    preview: typeof config.preview === "function",
     fields: await serializeFields(config.fields, new FieldAccessChecker("update", { user })),
     permissions: {
       read: await allowed(config.access?.read, user),
@@ -2792,6 +2886,13 @@ async function route(cms, ctx, method, segments, options) {
   if (second !== void 0 && third !== void 0) {
     return documentAction(cms, ctx, method, collection2, second, segments.slice(2));
   }
+  if (second === "preview") {
+    if (method !== "POST") throw methodNotAllowed(ctx, "POST");
+    const body = await readJson(ctx.request);
+    return {
+      body: await cms.preview(collection2, null, body, { ...access, ...parseDepth(ctx.url) })
+    };
+  }
   if (second === void 0) {
     if (method === "GET") {
       const query = parseListQuery(ctx.url);
@@ -2843,6 +2944,11 @@ async function documentAction(cms, ctx, method, collection2, id, path) {
     if (method !== "POST") throw methodNotAllowed(ctx, "POST");
     return { body: await cms.restoreVersion(collection2, id, versionId, { ...access, ...depth }) };
   }
+  if (path.length === 1 && action === "preview") {
+    if (method !== "POST") throw methodNotAllowed(ctx, "POST");
+    const body = await readJson(ctx.request);
+    return { body: await cms.preview(collection2, id, body, { ...access, ...depth }) };
+  }
   if (path.length === 1 && (action === "unpublish" || action === "discard-draft")) {
     if (method !== "POST") throw methodNotAllowed(ctx, "POST");
     const options = { ...access, ...depth };
@@ -2870,6 +2976,11 @@ async function globalAction(cms, ctx, method, slug, path) {
     if (method !== "POST") throw methodNotAllowed(ctx, "POST");
     return { body: await cms.restoreGlobalVersion(slug, versionId, { ...access, ...depth }) };
   }
+  if (path.length === 1 && action === "preview") {
+    if (method !== "POST") throw methodNotAllowed(ctx, "POST");
+    const body = await readJson(ctx.request);
+    return { body: await cms.previewGlobal(slug, body, { ...access, ...depth }) };
+  }
   if (path.length === 1 && (action === "unpublish" || action === "discard-draft")) {
     if (method !== "POST") throw methodNotAllowed(ctx, "POST");
     const options = { ...access, ...depth };

package/dist/live-preview.d.ts

@@ -0,0 +1,33 @@
+/** Sent by the admin to the preview frame whenever the form changes. */
+interface LivePreviewMessage<T = Record<string, unknown>> {
+    readonly type: 'easy-cms:preview';
+    /** Collection slug, or `undefined` for a global. */
+    readonly collection?: string;
+    /** Global slug, or `undefined` for a collection. */
+    readonly global?: string;
+    /** The document as it would be read after saving, relationships populated. */
+    readonly doc: T;
+}
+/** Sent by the page to the admin when it is ready, so the admin sends the current state. */
+declare const READY_MESSAGE = "easy-cms:preview-ready";
+interface LivePreviewOptions {
+    /**
+     * Origin(s) of the admin allowed to send updates. Default: the page's own origin, which fits
+     * the Nuxt and Next.js adapters (admin and site share it). Set it for a standalone server,
+     * e.g. `'https://cms.example.com'`.
+     */
+    readonly origin?: string | readonly string[];
+}
+/** True when the page is shown inside a frame (e.g. the admin's preview). */
+declare function isLivePreview(): boolean;
+/**
+ * Calls `onChange` with the document each time the admin's form changes. Returns a function
+ * that stops listening. Does nothing outside a frame, so it is safe to call on every page.
+ *
+ * ```ts
+ * const stop = subscribeLivePreview<Post>((doc) => render(doc))
+ * ```
+ */
+declare function subscribeLivePreview<T = Record<string, unknown>>(onChange: (doc: T, message: LivePreviewMessage<T>) => void, options?: LivePreviewOptions): () => void;
+
+export { type LivePreviewMessage, type LivePreviewOptions, READY_MESSAGE, isLivePreview, subscribeLivePreview };

package/dist/live-preview.js

@@ -0,0 +1,24 @@
+// src/live-preview.ts
+var READY_MESSAGE = "easy-cms:preview-ready";
+function isLivePreview() {
+  return typeof window !== "undefined" && window.parent !== window;
+}
+function subscribeLivePreview(onChange, options = {}) {
+  if (!isLivePreview()) return () => {
+  };
+  const allowed = [options.origin ?? window.location.origin].flat();
+  const listener = (event) => {
+    if (!allowed.includes(event.origin)) return;
+    const message = event.data;
+    if (message?.type !== "easy-cms:preview" || typeof message.doc !== "object") return;
+    onChange(message.doc, message);
+  };
+  window.addEventListener("message", listener);
+  window.parent.postMessage({ type: READY_MESSAGE }, "*");
+  return () => window.removeEventListener("message", listener);
+}
+export {
+  READY_MESSAGE,
+  isLivePreview,
+  subscribeLivePreview
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easy-cms/core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Embedded, code-first headless CMS for Nuxt and Next.js",
   "license": "MIT",
   "type": "module",
@@ -10,6 +10,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./live-preview": {
+      "types": "./dist/live-preview.d.ts",
+      "default": "./dist/live-preview.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [