@easy-cms/core 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -56,6 +56,14 @@ declare const anyone: Access;
 declare const isLoggedIn: Access;
 declare const isAdmin: Access;
 
+/** What a preview token opens: one document of a collection, or one global. */
+type PreviewTarget = {
+    readonly collection: string;
+    readonly id: string;
+} | {
+    readonly global: string;
+};
+
 interface Logger {
     info(message: string): void;
     warn(message: string): void;
@@ -193,6 +201,11 @@ interface BaseField<TType extends string, TValue> {
     readonly access?: FieldAccess;
     /** Stored but never returned by the API nor accepted as input (e.g. a password hash). */
     readonly hidden?: boolean;
+    /**
+     * One value per locale (needs `localization` in the config). Not for groups, arrays or
+     * hasMany fields: localize the fields inside a group or array instead.
+     */
+    readonly localized?: boolean;
 }
 interface TextField extends BaseField<'text', string> {
     readonly minLength?: number;
@@ -332,6 +345,23 @@ interface GlobalHooks {
     readonly afterChange?: readonly AfterChangeHook[];
     readonly afterRead?: readonly AfterReadHook[];
 }
+interface LocalizationConfig {
+    /** Content locales, e.g. `['th', 'en']`. */
+    readonly locales: readonly string[];
+    /** The locale used when none is given; its values also fill empty ones. Default: the first. */
+    readonly defaultLocale?: string;
+    /** Reads return the default locale's value when a locale's value is empty. Default true. */
+    readonly fallback?: boolean;
+}
+/**
+ * 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>;
+    /** The content locale being edited (with `localization`), otherwise the admin locale. */
+    readonly locale: string;
+}) => string | null | undefined;
 interface VersionsConfig {
     /** Versions kept per document; older ones are deleted. Default 50. */
     readonly max?: number;
@@ -354,6 +384,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 +396,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;
 }
@@ -430,6 +464,8 @@ interface Config {
      * `auth.trustedOrigins` are always allowed, with cookies. Default: none.
      */
     readonly cors?: readonly string[] | '*';
+    /** Content in several languages: fields with `localized: true` hold one value per locale. */
+    readonly localization?: LocalizationConfig | null;
     readonly routes?: RoutesConfig;
     readonly admin?: AdminConfig;
     readonly upload?: UploadConfig;
@@ -443,8 +479,10 @@ interface Config {
     readonly plugins?: readonly Plugin[];
 }
 /** The config after plugins ran, validation passed and defaults were applied. */
-interface ResolvedConfig extends Omit<Config, 'cors' | 'routes' | 'admin' | 'upload' | 'auth' | 'collections' | 'globals' | 'plugins'> {
+interface ResolvedConfig extends Omit<Config, 'cors' | 'localization' | 'routes' | 'admin' | 'upload' | 'auth' | 'collections' | 'globals' | 'plugins'> {
     readonly cors: readonly string[] | '*';
+    /** `null` without localization. */
+    readonly localization: Required<LocalizationConfig> | null;
     readonly routes: Required<RoutesConfig>;
     readonly admin: Required<AdminConfig>;
     readonly upload: Required<Omit<UploadConfig, 'storage'>> & Pick<UploadConfig, 'storage'>;
@@ -696,6 +734,11 @@ interface AccessOptions {
 interface DepthOptions extends AccessOptions {
     /** How many levels of relationships to populate. Default 1, maximum 3. */
     readonly depth?: number;
+    /**
+     * With `localization`: the locale to read, and for writes the locale the data is in. Default:
+     * the default locale. `'all'` reads (and writes) localized fields as `{ [locale]: value }`.
+     */
+    readonly locale?: string;
 }
 interface ReadOptions extends DepthOptions {
     /**
@@ -703,6 +746,8 @@ interface ReadOptions extends DepthOptions {
      * `drafts: true` are returned, including when populating relationships (FR-DRF-04).
      */
     readonly draft?: boolean;
+    /** Use the default locale's value when a localized value is empty. Default: `localization.fallback`. */
+    readonly fallbackLocale?: boolean;
 }
 interface FindOptions extends ReadOptions {
     readonly where?: Where;
@@ -738,6 +783,7 @@ declare class EasyCMS<C extends Config = Config> {
     count<S extends Slug<C>>(collection: S, options?: {
         where?: Where;
         draft?: boolean;
+        locale?: string;
     } & AccessOptions): Promise<number>;
     create<S extends Slug<C>>(collection: S, data: Create<C, S>, options?: DepthOptions): Promise<Doc<C, S>>;
     /**
@@ -771,6 +817,34 @@ 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>>>;
+    /**
+     * A token that lets a page read one document's current draft for a while (default one hour),
+     * without a login: `GET /api/cms/:collection/:id?preview=<token>`. The admin adds one to the
+     * preview URL as `easy-cms-preview`, for sites on another origin.
+     */
+    createPreviewToken(target: {
+        collection: string;
+        id: ID;
+    } | {
+        global: string;
+    }, options?: {
+        expiresIn?: number;
+    }): string;
+    /** What a preview token opens, or `null` when it is invalid or expired. */
+    verifyPreviewToken(token: string | null | undefined): (PreviewTarget & {
+        expiresAt: number;
+    }) | null;
+    /** 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>>;
@@ -814,6 +888,14 @@ declare class EasyCMS<C extends Config = Config> {
     private output;
     /** Creates a document: access, input filtering, hooks, validation, then afterChange. */
     private createDocument;
+    /** The locale for an operation; `undefined` without localization. Throws on unknown locales. */
+    private localeOf;
+    /** Stored localized maps → the values of the requested locale. */
+    private pick;
+    /** Input for one locale → stored localized maps, keeping the other locales from `current`. */
+    private toMaps;
+    /** Makes `where` match localized fields in the operation's locale. */
+    private whereFor;
     /** Drafts are kept as versions (instead of unpublishing) when both are enabled. */
     private separateDrafts;
     /** Replaces published documents that have a newer draft with that draft. */
@@ -839,6 +921,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;
@@ -951,6 +1039,8 @@ declare class PayloadTooLargeError extends EasyCMSError {
     constructor(message: string);
 }
 
+type Localization = Required<LocalizationConfig>;
+
 type Data = Record<string, unknown>;
 /**
  * Turns text into a URL slug. Keeps letters and digits of any script,
@@ -958,11 +1048,11 @@ type Data = Record<string, unknown>;
  */
 declare function slugify(text: string): string;
 /** Fills in `defaultValue` for fields that are missing, including inside groups and array rows. */
-declare function applyDefaults(fields: readonly Field[], data: Data): Data;
+declare function applyDefaults(fields: readonly Field[], data: Data, localization?: Localization | null): Data;
 /** Gives every field a value (`null`, `[]` or a nested object) so documents always have the same shape. */
 declare function fillMissing(fields: readonly Field[], data: Data): Data;
 /** Fills empty `slug` fields from their `from` field. Does not check uniqueness. */
-declare function generateSlugs(fields: readonly Field[], data: Data): Data;
+declare function generateSlugs(fields: readonly Field[], data: Data, localization?: Localization | null): Data;
 /**
  * Merges an update into the stored document. Top-level fields and group
  * fields merge key by key; arrays and hasMany values are replaced.
@@ -982,6 +1072,13 @@ interface ValidateOptions {
     readonly skipRequired?: boolean;
     /** The whole top-level document, passed to custom `validate` functions. */
     readonly root: Data;
+    /** Localized fields hold `{ [locale]: value }`; each value is validated. */
+    readonly localization?: Localization | null;
+    /**
+     * The locale being written: `required` and custom `validate` apply to its values, and its
+     * errors use the plain field path. Default: the default locale.
+     */
+    readonly locale?: string;
 }
 interface ValidateResult {
     /** Only known fields, with values normalized (ids parsed, dates as ISO strings, row ids filled). */
@@ -1066,6 +1163,8 @@ interface AdminField {
     fields?: AdminField[];
     /** The current user may not change this field. */
     readOnly?: boolean;
+    /** One value per content locale. */
+    localized?: boolean;
 }
 interface AdminCollection {
     slug: string;
@@ -1076,6 +1175,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 +1190,8 @@ interface AdminGlobal {
     label?: Label;
     drafts: boolean;
     versions: boolean;
+    /** Has live preview (`preview` in the config). */
+    preview: boolean;
     fields: AdminField[];
     permissions: {
         read: boolean;
@@ -1097,6 +1200,11 @@ interface AdminGlobal {
 }
 interface AdminSchema {
     locale: AdminLocale;
+    /** Content locales, when the config has `localization`. */
+    localization: {
+        locales: string[];
+        defaultLocale: string;
+    } | null;
     collections: AdminCollection[];
     globals: AdminGlobal[];
 }
@@ -1129,4 +1237,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 LocalizationConfig, 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 PreviewTarget, 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

@@ -419,6 +419,30 @@ function safeEqual(a, b) {
   const right = Buffer.from(b);
   return left.length === right.length && timingSafeEqual2(left, right);
 }
+function signPreviewToken(secret, target, expiresAt) {
+  const payload = Buffer.from(
+    JSON.stringify(
+      "global" in target ? { g: target.global, e: expiresAt } : { c: target.collection, i: target.id, e: expiresAt }
+    )
+  ).toString("base64url");
+  return `${payload}.${hmac(secret, `preview:${payload}`)}`;
+}
+function verifyPreviewToken(secret, token, now = Date.now()) {
+  const dot = token.lastIndexOf(".");
+  if (dot <= 0) return null;
+  const payload = token.slice(0, dot);
+  if (!safeEqual(token.slice(dot + 1), hmac(secret, `preview:${payload}`))) return null;
+  try {
+    const data = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    if (typeof data.e !== "number" || data.e <= now) return null;
+    if (typeof data.g === "string") return { global: data.g, expiresAt: data.e };
+    if (typeof data.c === "string" && typeof data.i === "string")
+      return { collection: data.c, id: data.i, expiresAt: data.e };
+    return null;
+  } catch {
+    return null;
+  }
+}
 
 // src/auth/auth.ts
 var INVALID = "Invalid email or password";
@@ -620,18 +644,30 @@ var isEmpty = (value) => value === void 0 || value === null || value === "";
 function slugify(text) {
   return text.normalize("NFKC").toLowerCase().replace(/[^\p{L}\p{M}\p{N}]+/gu, "-").replace(/^-+|-+$/g, "");
 }
-function applyDefaults(fields, data) {
+function applyDefaults(fields, data, localization = null) {
   const result = { ...data };
   for (const field of fields) {
     const value = result[field.name];
     if (field.type === "group") {
-      result[field.name] = applyDefaults(field.fields, isPlainObject(value) ? value : {});
+      result[field.name] = applyDefaults(
+        field.fields,
+        isPlainObject(value) ? value : {},
+        localization
+      );
     } else if (field.type === "array") {
       if (Array.isArray(value)) {
         result[field.name] = value.map(
-          (row) => isPlainObject(row) ? applyDefaults(field.fields, row) : row
+          (row) => isPlainObject(row) ? applyDefaults(field.fields, row, localization) : row
         );
       }
+    } else if (field.localized && localization && field.defaultValue !== void 0) {
+      const map = isPlainObject(value) ? value : {};
+      if (map[localization.defaultLocale] === void 0) {
+        result[field.name] = {
+          ...map,
+          [localization.defaultLocale]: structuredClone(field.defaultValue)
+        };
+      }
     } else if (value === void 0 && field.defaultValue !== void 0) {
       result[field.name] = structuredClone(field.defaultValue);
     }
@@ -650,22 +686,34 @@ function fillMissing(fields, data) {
   }
   return result;
 }
-function generateSlugs(fields, data) {
+function generateSlugs(fields, data, localization = null) {
   const result = { ...data };
   for (const field of fields) {
-    if (field.type === "slug") {
+    if (field.type === "slug" && field.localized && localization) {
+      const map = isPlainObject(result[field.name]) ? result[field.name] : {};
+      const source = field.from ? result[field.from] : void 0;
+      const next = { ...map };
+      for (const locale of localization.locales) {
+        const current = map[locale];
+        const from = isPlainObject(source) ? source[locale] : source;
+        if (typeof current === "string" && current !== "") next[locale] = slugify(current);
+        else if (typeof from === "string" && from.trim() !== "") next[locale] = slugify(from);
+      }
+      result[field.name] = next;
+    } else if (field.type === "slug") {
       const current = result[field.name];
       if (typeof current === "string" && current !== "") {
         result[field.name] = slugify(current);
       } else if (field.from) {
-        const source = result[field.from];
+        const raw = result[field.from];
+        const source = isPlainObject(raw) && localization ? raw[localization.defaultLocale] : raw;
         if (typeof source === "string" && source.trim() !== "") result[field.name] = slugify(source);
       }
     } else if (field.type === "group" && isPlainObject(result[field.name])) {
-      result[field.name] = generateSlugs(field.fields, result[field.name]);
+      result[field.name] = generateSlugs(field.fields, result[field.name], localization);
     } else if (field.type === "array" && Array.isArray(result[field.name])) {
       result[field.name] = result[field.name].map(
-        (row) => isPlainObject(row) ? generateSlugs(field.fields, row) : row
+        (row) => isPlainObject(row) ? generateSlugs(field.fields, row, localization) : row
       );
     }
   }
@@ -717,6 +765,42 @@ async function validateFields(fields, input, options, prefix = "") {
       references.push(...sub.references);
       continue;
     }
+    const localization = options.localization;
+    if (field.localized && localization) {
+      if (!isEmpty(raw) && !isPlainObject(raw)) {
+        fail("must be an object with one value per locale");
+        continue;
+      }
+      const map = isPlainObject(raw) ? raw : {};
+      const written = options.locale ?? localization.defaultLocale;
+      const out = {};
+      for (const locale of localization.locales) {
+        const own = locale === written;
+        const localePath = own ? path : `${path}.${locale}`;
+        const failLocale = (message) => errors.push({ field: localePath, message });
+        const value2 = map[locale];
+        if (isEmpty(value2)) {
+          if (own && field.required && !options.skipRequired) failLocale("is required");
+          out[locale] = null;
+          if (own && !field.required) await runCustom(field, null, options, failLocale);
+          continue;
+        }
+        const normalized = await normalizeValue(
+          field,
+          value2,
+          localePath,
+          options,
+          failLocale,
+          errors,
+          references
+        );
+        if (normalized === void 0) continue;
+        out[locale] = normalized;
+        if (own) await runCustom(field, normalized, options, failLocale);
+      }
+      data[field.name] = out;
+      continue;
+    }
     if (isEmpty(raw) || Array.isArray(raw) && raw.length === 0) {
       if (field.required && !options.skipRequired) fail("is required");
       data[field.name] = field.type === "array" || isHasMany(field) ? [] : null;
@@ -889,6 +973,7 @@ function validateConfig(config) {
   validateUpload(config, add);
   validateAuth(config, add);
   validateCors(config.cors, add);
+  validateLocalization(config, add);
   const collections = asArray(config.collections, "collections", add);
   const globals = asArray(config.globals, "globals", add);
   const collectionSlugs = /* @__PURE__ */ new Set([...BUILTIN_COLLECTIONS]);
@@ -965,6 +1050,76 @@ function validateAuth(config, add) {
     }
   }
 }
+var LOCALE_PATTERN = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+var LOCALIZABLE = /* @__PURE__ */ new Set([
+  "text",
+  "textarea",
+  "email",
+  "slug",
+  "richText",
+  "number",
+  "boolean",
+  "date",
+  "json",
+  "select",
+  "upload",
+  "relationship"
+]);
+function validateLocalization(config, add) {
+  const localization = config.localization;
+  if (localization !== void 0 && localization !== null) {
+    const locales = localization?.locales;
+    if (!Array.isArray(locales) || locales.length === 0) {
+      add("localization.locales", "must be a non-empty list of locales", "locales: ['th', 'en']");
+    } else {
+      const seen = /* @__PURE__ */ new Set();
+      for (const [i, locale] of locales.entries()) {
+        if (typeof locale !== "string" || !LOCALE_PATTERN.test(locale)) {
+          add(
+            `localization.locales[${i}]`,
+            `must be a locale code like "th" or "en-US" (got ${JSON.stringify(locale)})`
+          );
+        } else if (seen.has(locale)) {
+          add(`localization.locales[${i}]`, `duplicate locale "${locale}"`);
+        }
+        seen.add(locale);
+      }
+      const fallbackDefault = localization.defaultLocale;
+      if (fallbackDefault !== void 0 && !locales.includes(fallbackDefault)) {
+        add("localization.defaultLocale", `must be one of the locales (got "${fallbackDefault}")`);
+      }
+    }
+  }
+  const walk = (fields, path) => {
+    if (!Array.isArray(fields)) return;
+    for (const field of fields) {
+      if (typeof field?.name !== "string") continue;
+      const fieldPath = `${path}.${field.name}`;
+      if (field.localized) {
+        if (!localization) {
+          add(
+            `${fieldPath}.localized`,
+            "needs `localization` in the config",
+            "localization: { locales: ['th', 'en'] }"
+          );
+        } else if (!LOCALIZABLE.has(field.type)) {
+          add(
+            `${fieldPath}.localized`,
+            `${field.type} fields cannot be localized`,
+            "localize the fields inside it instead"
+          );
+        } else if ("hasMany" in field && field.hasMany) {
+          add(`${fieldPath}.localized`, "hasMany fields cannot be localized yet");
+        }
+      }
+      if (field.type === "group" || field.type === "array")
+        walk(field.fields, `${fieldPath}.fields`);
+    }
+  };
+  for (const [i, c] of (config.collections ?? []).entries())
+    walk(c?.fields, `collections[${i}].fields`);
+  for (const [i, g] of (config.globals ?? []).entries()) walk(g?.fields, `globals[${i}].fields`);
+}
 function validateCors(cors, add) {
   if (cors === void 0 || cors === "*") return;
   if (!Array.isArray(cors)) {
@@ -1032,6 +1187,14 @@ 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",
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: an example shown to the user
+      "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);
@@ -1172,6 +1335,11 @@ async function resolveConfig(input) {
   const result = {
     ...rest,
     cors: config.cors ?? [],
+    localization: config.localization ? {
+      locales: config.localization.locales,
+      defaultLocale: config.localization.defaultLocale ?? config.localization.locales[0] ?? "",
+      fallback: config.localization.fallback ?? true
+    } : null,
     routes: { api: `/${(config.routes?.api ?? DEFAULT_API_PATH).replace(/^\/+|\/+$/g, "")}` },
     admin: {
       path: config.admin?.path ?? DEFAULT_ADMIN_PATH,
@@ -1253,6 +1421,89 @@ async function loadConfig(options = {}) {
 // src/local-api.ts
 import { randomBytes as randomBytes3 } from "crypto";
 
+// src/localization.ts
+var ALL_LOCALES = "all";
+var isPlainObject2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isEmpty2 = (value) => value === void 0 || value === null || value === "";
+function pickLocale(fields, data, locale, localization, fallback) {
+  if (locale === ALL_LOCALES) return data;
+  const result = { ...data };
+  for (const field of fields) {
+    const value = result[field.name];
+    if (field.type === "group" && isPlainObject2(value)) {
+      result[field.name] = pickLocale(field.fields, value, locale, localization, fallback);
+    } else if (field.type === "array" && Array.isArray(value)) {
+      result[field.name] = value.map(
+        (row) => isPlainObject2(row) ? pickLocale(field.fields, row, locale, localization, fallback) : row
+      );
+    } else if (field.localized) {
+      const map = isPlainObject2(value) ? value : {};
+      const own = map[locale];
+      result[field.name] = isEmpty2(own) && fallback ? map[localization.defaultLocale] ?? null : own ?? null;
+    }
+  }
+  return result;
+}
+function toLocaleMaps(fields, input, current, locale) {
+  const result = { ...input };
+  for (const field of fields) {
+    if (!Object.hasOwn(input, field.name)) continue;
+    const value = input[field.name];
+    const previous = current[field.name];
+    if (field.type === "group" && isPlainObject2(value)) {
+      result[field.name] = toLocaleMaps(
+        field.fields,
+        value,
+        isPlainObject2(previous) ? previous : {},
+        locale
+      );
+    } else if (field.type === "array" && Array.isArray(value)) {
+      const rows = new Map(
+        (Array.isArray(previous) ? previous : []).filter(isPlainObject2).map((row) => [String(row.id), row])
+      );
+      result[field.name] = value.map(
+        (row) => isPlainObject2(row) ? toLocaleMaps(field.fields, row, rows.get(String(row.id)) ?? {}, locale) : row
+      );
+    } else if (field.localized) {
+      const map = isPlainObject2(previous) ? previous : {};
+      result[field.name] = { ...map, [locale]: value };
+    }
+  }
+  return result;
+}
+function localizePath(fields, path, locale) {
+  const segments = path.split(".");
+  let list = fields;
+  for (let i = 0; i < segments.length; i++) {
+    const field = list.find((f) => f.name === segments[i]);
+    if (!field) return path;
+    if (field.type === "group" || field.type === "array") {
+      list = field.fields;
+      continue;
+    }
+    if (field.localized && i === segments.length - 1) return `${path}.${locale}`;
+    return path;
+  }
+  return path;
+}
+function localizeWhere(fields, where, locale) {
+  if (!where) return where;
+  const out = {};
+  for (const [key2, value] of Object.entries(where)) {
+    if ((key2 === "and" || key2 === "or") && Array.isArray(value)) {
+      out[key2] = value.map((w) => localizeWhere(fields, w, locale));
+    } else {
+      out[localizePath(fields, key2, locale)] = value;
+    }
+  }
+  return out;
+}
+function localizeSort(fields, sort, locale) {
+  return sort.map(
+    (entry) => entry.startsWith("-") ? `-${localizePath(fields, entry.slice(1), locale)}` : localizePath(fields, entry, locale)
+  );
+}
+
 // src/logger.ts
 var consoleLogger = {
   info: (message) => console.info(`[easy-cms] ${message}`),
@@ -1638,12 +1889,18 @@ var EasyCMS = class {
     if (!Number.isInteger(limit) || limit < 0)
       throw new QueryError("limit must be a non-negative integer");
     if (!Number.isInteger(page) || page < 1) throw new QueryError("page must be a positive integer");
-    const where = draftWhere(
+    const where = this.whereFor(
       config,
-      options.draft,
-      await this.readWhere(config, guard, options.where)
+      draftWhere(config, options.draft, await this.readWhere(config, guard, options.where)),
+      options
+    );
+    const requested = options.sort === void 0 ? ["-createdAt"] : [options.sort].flat();
+    const locale = this.localeOf(options);
+    const sort = locale === void 0 ? requested : localizeSort(
+      config.fields,
+      requested,
+      locale === ALL_LOCALES ? this.config.localization?.defaultLocale ?? locale : locale
     );
-    const sort = options.sort === void 0 ? ["-createdAt"] : [options.sort].flat();
     const result = await this.db.find({ collection: collection2, where, sort, limit, page });
     const found = options.draft ? await this.withDrafts(config, result.docs) : result.docs;
     const docs = await this.output(config, found, guard, options);
@@ -1654,7 +1911,11 @@ var EasyCMS = class {
     const guard = guardOf(options);
     const parsed = parseId(id);
     if (parsed === void 0) return null;
-    const where = draftWhere(config, options.draft, await this.readWhere(config, guard, void 0));
+    const where = this.whereFor(
+      config,
+      draftWhere(config, options.draft, await this.readWhere(config, guard, void 0)),
+      options
+    );
     const doc = where ? (await this.db.find({
       collection: collection2,
       where: andWhere(where, { id: { equals: parsed } }),
@@ -1669,10 +1930,14 @@ var EasyCMS = class {
   }
   async count(collection2, options = {}) {
     const config = this.collection(collection2);
-    const where = draftWhere(
+    const where = this.whereFor(
       config,
-      options.draft,
-      await this.readWhere(config, guardOf(options), options.where)
+      draftWhere(
+        config,
+        options.draft,
+        await this.readWhere(config, guardOf(options), options.where)
+      ),
+      options
     );
     return this.db.count({ collection: collection2, where });
   }
@@ -1822,8 +2087,124 @@ var EasyCMS = class {
       collection2,
       parsed,
       config.drafts ? { ...data, status: "draft" } : data,
+      options,
+      "restore"
+    );
+  }
+  /**
+   * 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 localized = this.toMaps(config, filtered, base ?? {}, options);
+    const merged = base ? mergeForUpdate(config.fields, base, localized) : applyDefaults(config.fields, localized, this.config.localization);
+    if (config.drafts) merged.status = filtered.status ?? base?.status ?? "draft";
+    const doc = await this.previewDoc(
+      config,
+      generateSlugs(config.fields, merged, this.config.localization),
+      {
+        id: parsed ?? 0,
+        createdAt: base?.createdAt ?? (/* @__PURE__ */ new Date()).toISOString()
+      },
       options
     );
+    const [out] = await this.output(config, [doc], guard, { ...options, draft: true });
+    return { doc: out, url: this.previewURL(config, out, options) };
+  }
+  /**
+   * A token that lets a page read one document's current draft for a while (default one hour),
+   * without a login: `GET /api/cms/:collection/:id?preview=<token>`. The admin adds one to the
+   * preview URL as `easy-cms-preview`, for sites on another origin.
+   */
+  createPreviewToken(target, options = {}) {
+    const seconds = options.expiresIn ?? 60 * 60;
+    const normalized = "global" in target ? target : { collection: target.collection, id: String(target.id) };
+    return signPreviewToken(this.config.secret, normalized, Date.now() + seconds * 1e3);
+  }
+  /** What a preview token opens, or `null` when it is invalid or expired. */
+  verifyPreviewToken(token) {
+    return token ? verifyPreviewToken(this.config.secret, token) : null;
+  }
+  /** 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, this.toMaps(config, input, current, options)),
+        this.config.localization
+      ),
+      this.config.localization
+    );
+    if (config.drafts) merged.status = input.status ?? current.status ?? "draft";
+    const doc = await this.previewDoc(config, merged, { id: 0 }, options);
+    const [out] = await this.output(config, [doc], guard, { ...options, draft: true });
+    const { id: _id, ...global2 } = out;
+    return { doc: global2, url: this.previewURL(config, global2, options) };
+  }
+  /** Coerces preview input like a save would, keeping values that would fail validation. */
+  async previewDoc(config, data, system, options = {}) {
+    const locale = this.localeOf(options);
+    const { data: clean } = await validateFields(config.fields, data, {
+      operation: "update",
+      root: data,
+      skipRequired: true,
+      localization: this.config.localization,
+      ...locale !== void 0 && locale !== ALL_LOCALES ? { locale } : {}
+    });
+    return {
+      ...data,
+      ...clean,
+      ...config.drafts ? { status: data.status } : {},
+      ...system,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  previewURL(config, doc, options) {
+    if (!config.preview) return null;
+    const content = this.localeOf(options);
+    const locale = content && content !== ALL_LOCALES ? content : this.config.admin.locale;
+    try {
+      return config.preview({ doc, 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);
@@ -1848,7 +2229,8 @@ var EasyCMS = class {
       input,
       this.fieldChecker("update", guard, parsed, input)
     );
-    let merged = mergeForUpdate(config.fields, current, filtered);
+    const localized = mode === "restore" ? filtered : this.toMaps(config, filtered, current, options);
+    let merged = mergeForUpdate(config.fields, current, localized);
     if (config.drafts)
       merged.status = Object.hasOwn(filtered, "status") ? filtered.status : current.status;
     const base = this.hookArgs(config, guard);
@@ -1860,9 +2242,10 @@ var EasyCMS = class {
     );
     let prepared = await this.prepare(
       config,
-      generateSlugs(config.fields, merged),
+      generateSlugs(config.fields, merged, this.config.localization),
       "update",
-      parsed
+      parsed,
+      options
     );
     prepared = await this.transform(
       config.hooks?.beforeChange,
@@ -1871,7 +2254,7 @@ var EasyCMS = class {
       prepared
     );
     const now = (/* @__PURE__ */ new Date()).toISOString();
-    if (mode === "save" && this.separateDrafts(config) && existing.status === "published" && prepared.status === "draft") {
+    if (mode !== "unpublish" && this.separateDrafts(config) && existing.status === "published" && prepared.status === "draft") {
       if (password !== void 0) {
         throw new ValidationError(collection2, [
           { field: "password", message: "cannot be changed in a draft; publish instead" }
@@ -1937,7 +2320,10 @@ var EasyCMS = class {
     await this.checkGlobalAccess(config, "read", guard);
     const saved = await this.db.findGlobal({ slug });
     const stored = saved && options.draft ? await this.globalDraft(config, saved) : saved;
-    const data = fillMissing(config.fields, applyDefaults(config.fields, stored ?? {}));
+    const data = fillMissing(
+      config.fields,
+      applyDefaults(config.fields, stored ?? {}, this.config.localization)
+    );
     if (!stored) {
       data.updatedAt = null;
       if (config.drafts) data.status = "draft";
@@ -1974,7 +2360,10 @@ var EasyCMS = class {
     const config = await this.globalVersionTarget(slug, options);
     const version = await this.versions.get(globalParent(slug), 0, versionId);
     if (!version) return null;
-    const data = fillMissing(config.fields, applyDefaults(config.fields, version.data));
+    const data = fillMissing(
+      config.fields,
+      applyDefaults(config.fields, version.data, this.config.localization)
+    );
     const [out] = await this.output(config, [{ ...data, id: 0 }], guardOf(options), {
       ...options,
       draft: true
@@ -1991,7 +2380,8 @@ var EasyCMS = class {
     return this.saveGlobal(
       slug,
       config.drafts ? { ...data, status: "draft" } : data,
-      options
+      options,
+      "restore"
     );
   }
   async globalVersionTarget(slug, options) {
@@ -2018,13 +2408,19 @@ var EasyCMS = class {
     );
     const existing = await this.db.findGlobal({ slug }) ?? {};
     const current = await this.globalDraft(config, existing);
+    const localized = mode === "restore" ? input : this.toMaps(config, input, current, options);
     const merged = generateSlugs(
       config.fields,
-      applyDefaults(config.fields, mergeForUpdate(config.fields, current, input))
+      applyDefaults(
+        config.fields,
+        mergeForUpdate(config.fields, current, localized),
+        this.config.localization
+      ),
+      this.config.localization
     );
     if (config.drafts) merged.status = input.status ?? current.status ?? "draft";
     const base = this.hookArgs(config, guard);
-    let prepared = await this.prepare(config, merged, "update", void 0);
+    let prepared = await this.prepare(config, merged, "update", void 0, options);
     prepared = await this.transform(
       config.hooks?.beforeChange,
       "data",
@@ -2032,7 +2428,7 @@ var EasyCMS = class {
       prepared
     );
     const now = (/* @__PURE__ */ new Date()).toISOString();
-    if (mode === "save" && this.separateDrafts(config) && existing.status === "published" && prepared.status === "draft") {
+    if (mode !== "unpublish" && this.separateDrafts(config) && existing.status === "published" && prepared.status === "draft") {
       const draft = { ...prepared, updatedAt: now };
       await this.saveVersion(config, globalParent(slug), 0, draft, guard);
       await this.notify(config.hooks?.afterChange, "afterChange", slug, {
@@ -2146,16 +2542,19 @@ var EasyCMS = class {
       if (where === null) return [];
       const found = await this.db.find({
         collection: target.slug,
-        where: draftWhere(target, options.draft, where),
+        where: this.whereFor(target, draftWhere(target, options.draft, where), options),
         sort: [],
         limit: 0,
         page: 1
       });
       const docs2 = options.draft ? await this.withDrafts(target, found.docs) : found.docs;
-      return Promise.all(docs2.map((d) => finish(target, d)));
+      return Promise.all(
+        docs2.map((d) => finish(target, this.pick(target, d, options)))
+      );
     };
     const depth = Math.max(0, Math.min(MAX_DEPTH, Math.trunc(options.depth ?? DEFAULT_DEPTH)));
-    const populated = await populate(load, this.config.collections, config.fields, docs, depth);
+    const localized = docs.map((d) => this.pick(config, d, options));
+    const populated = await populate(load, this.config.collections, config.fields, localized, depth);
     return Promise.all(populated.map((d) => finish(config, d)));
   }
   /** Creates a document: access, input filtering, hooks, validation, then afterChange. */
@@ -2178,7 +2577,11 @@ var EasyCMS = class {
       this.fieldChecker("update", guard, void 0, input)
     );
     const base = this.hookArgs(config, hookGuard ?? guard);
-    let data = applyDefaults(config.fields, filtered);
+    let data = applyDefaults(
+      config.fields,
+      this.toMaps(config, filtered, {}, options),
+      this.config.localization
+    );
     data = await this.transform(
       config.hooks?.beforeValidate,
       "data",
@@ -2187,9 +2590,10 @@ var EasyCMS = class {
     );
     let prepared = await this.prepare(
       config,
-      generateSlugs(config.fields, data),
+      generateSlugs(config.fields, data, this.config.localization),
       "create",
-      void 0
+      void 0,
+      options
     );
     prepared = await this.transform(
       config.hooks?.beforeChange,
@@ -2212,6 +2616,43 @@ var EasyCMS = class {
     const [out] = await this.output(config, [doc], hookGuard ?? guard, { ...options, draft: true });
     return out;
   }
+  /** The locale for an operation; `undefined` without localization. Throws on unknown locales. */
+  localeOf(options) {
+    const localization = this.config.localization;
+    if (!localization) return void 0;
+    const locale = options.locale ?? localization.defaultLocale;
+    if (locale !== ALL_LOCALES && !localization.locales.includes(locale)) {
+      throw new QueryError(
+        `Unknown locale "${locale}" (use one of: ${localization.locales.join(", ")}, ${ALL_LOCALES})`
+      );
+    }
+    return locale;
+  }
+  /** Stored localized maps → the values of the requested locale. */
+  pick(config, doc, options) {
+    const localization = this.config.localization;
+    const locale = this.localeOf(options);
+    if (!localization || locale === void 0) return doc;
+    const fallback = options.fallbackLocale ?? localization.fallback;
+    return pickLocale(config.fields, doc, locale, localization, fallback);
+  }
+  /** Input for one locale → stored localized maps, keeping the other locales from `current`. */
+  toMaps(config, input, current, options) {
+    const locale = this.localeOf(options);
+    if (locale === void 0 || locale === ALL_LOCALES) return input;
+    return toLocaleMaps(config.fields, input, current, locale);
+  }
+  /** Makes `where` match localized fields in the operation's locale. */
+  whereFor(config, where, options) {
+    const locale = this.localeOf(options);
+    const localization = this.config.localization;
+    if (locale === void 0 || !localization) return where;
+    return localizeWhere(
+      config.fields,
+      where,
+      locale === ALL_LOCALES ? localization.defaultLocale : locale
+    );
+  }
   /** Drafts are kept as versions (instead of unpublishing) when both are enabled. */
   separateDrafts(config) {
     return config.drafts === true && versionLimit(config) !== void 0;
@@ -2302,12 +2743,15 @@ var EasyCMS = class {
     return result;
   }
   /** Validates, checks uniqueness and references. Returns clean data or throws `ValidationError`. */
-  async prepare(config, data, operation, selfId) {
+  async prepare(config, data, operation, selfId, options = {}) {
     const isDraft = config.drafts === true && (data.status ?? "draft") === "draft";
+    const locale = this.localeOf(options);
     const result = await validateFields(config.fields, data, {
       operation,
       root: data,
-      skipRequired: isDraft
+      skipRequired: isDraft,
+      localization: this.config.localization,
+      ...locale !== void 0 && locale !== ALL_LOCALES ? { locale } : {}
     });
     const errors = [...result.errors];
     const clean = { ...result.data };
@@ -2349,14 +2793,26 @@ var EasyCMS = class {
     }
   }
   async makeSlugsUnique(config, data, selfId) {
-    for (const field of config.fields) {
-      const base = data[field.name];
-      if (field.type !== "slug" || typeof base !== "string" || base === "") continue;
+    const unique = async (path, base) => {
       let candidate = base;
-      for (let n = 2; await this.isTaken(config.slug, field.name, candidate, selfId); n++) {
+      for (let n = 2; await this.isTaken(config.slug, path, candidate, selfId); n++) {
         candidate = `${base}-${n}`;
       }
-      data[field.name] = candidate;
+      return candidate;
+    };
+    for (const field of config.fields) {
+      if (field.type !== "slug") continue;
+      const value = data[field.name];
+      if (field.localized && value && typeof value === "object") {
+        const map = { ...value };
+        for (const [locale, slug] of Object.entries(map)) {
+          if (typeof slug === "string" && slug !== "")
+            map[locale] = await unique(`${field.name}.${locale}`, slug);
+        }
+        data[field.name] = map;
+      } else if (typeof value === "string" && value !== "") {
+        data[field.name] = await unique(field.name, value);
+      }
     }
   }
   async checkUnique(config, data, selfId) {
@@ -2364,8 +2820,16 @@ var EasyCMS = class {
     for (const field of config.fields) {
       const value = data[field.name];
       if (!field.unique || field.type === "slug" || value === null || value === void 0) continue;
-      if (await this.isTaken(config.slug, field.name, value, selfId)) {
-        errors.push({ field: field.name, message: "must be unique" });
+      const checks = field.localized && typeof value === "object" ? Object.entries(value).map(([locale, v]) => [
+        `${field.name}.${locale}`,
+        locale === this.config.localization?.defaultLocale ? field.name : `${field.name}.${locale}`,
+        v
+      ]) : [[field.name, field.name, value]];
+      for (const [path, errorField, v] of checks) {
+        if (v === null || v === void 0) continue;
+        if (await this.isTaken(config.slug, path, v, selfId)) {
+          errors.push({ field: errorField, message: "must be unique" });
+        }
       }
     }
     return errors;
@@ -2445,7 +2909,7 @@ function asObject(data, name) {
 async function allowed(access, user) {
   return await evaluateAccess(access, { user }) !== false;
 }
-async function serializeFields(fields, update) {
+async function serializeFields(fields, update, localized) {
   const out = [];
   for (const field of fields) {
     if (field.hidden) continue;
@@ -2455,6 +2919,7 @@ async function serializeFields(fields, update) {
     if (field.unique) f.unique = true;
     if (field.defaultValue !== void 0) f.defaultValue = field.defaultValue;
     if (!await update.allows(field)) f.readOnly = true;
+    if (field.localized && localized) f.localized = true;
     switch (field.type) {
       case "text":
       case "textarea":
@@ -2484,22 +2949,27 @@ async function serializeFields(fields, update) {
       case "array":
         if (field.minRows !== void 0) f.minRows = field.minRows;
         if (field.maxRows !== void 0) f.maxRows = field.maxRows;
-        f.fields = await serializeFields(field.fields, update);
+        f.fields = await serializeFields(field.fields, update, localized);
         break;
       case "group":
-        f.fields = await serializeFields(field.fields, update);
+        f.fields = await serializeFields(field.fields, update, localized);
         break;
     }
     out.push(f);
   }
   return out;
 }
-async function collection(config, user) {
+async function collection(config, user, localized) {
   const result = {
     slug: config.slug,
     drafts: config.drafts === true,
     versions: Boolean(config.versions),
-    fields: await serializeFields(config.fields, new FieldAccessChecker("update", { user })),
+    preview: typeof config.preview === "function",
+    fields: await serializeFields(
+      config.fields,
+      new FieldAccessChecker("update", { user }),
+      localized
+    ),
     permissions: {
       read: await allowed(config.access?.read, user),
       create: await allowed(config.access?.create, user),
@@ -2511,12 +2981,17 @@ async function collection(config, user) {
   if (config.useAsTitle) result.useAsTitle = config.useAsTitle;
   return result;
 }
-async function global(config, user) {
+async function global(config, user, localized) {
   const result = {
     slug: config.slug,
     drafts: config.drafts === true,
     versions: Boolean(config.versions),
-    fields: await serializeFields(config.fields, new FieldAccessChecker("update", { user })),
+    preview: typeof config.preview === "function",
+    fields: await serializeFields(
+      config.fields,
+      new FieldAccessChecker("update", { user }),
+      localized
+    ),
     permissions: {
       read: await allowed(config.access?.read, user),
       update: await allowed(config.access?.update, user)
@@ -2527,10 +3002,13 @@ async function global(config, user) {
 }
 async function adminSchema(cms, user) {
   const collections = cms.config.collections.filter((c) => !INTERNAL_COLLECTIONS.has(c.slug));
+  const localization = cms.config.localization;
+  const localized = localization !== null;
   return {
     locale: cms.config.admin.locale,
-    collections: await Promise.all(collections.map((c) => collection(c, user))),
-    globals: await Promise.all(cms.config.globals.map((g) => global(g, user)))
+    localization: localization ? { locales: [...localization.locales], defaultLocale: localization.defaultLocale } : null,
+    collections: await Promise.all(collections.map((c) => collection(c, user, localized))),
+    globals: await Promise.all(cms.config.globals.map((g) => global(g, user, localized)))
   };
 }
 
@@ -2701,7 +3179,7 @@ function withHeaders(response, extra) {
 }
 async function route(cms, ctx, method, segments, options) {
   const [first, second, third] = segments;
-  const access = { overrideAccess: false, user: ctx.user };
+  const access = { overrideAccess: false, user: ctx.user, ...parseLocale(ctx.url) };
   const draft = ctx.user !== null && ctx.url.searchParams.get("draft") === "true";
   if (segments.length === 0) throw new HttpError("Not found", 404);
   if (first === USERS && second !== void 0 && third === void 0 && !/^\d+$/.test(second)) {
@@ -2766,8 +3244,19 @@ async function route(cms, ctx, method, segments, options) {
     if (!cms.config.globals.some((g) => g.slug === second))
       throw new HttpError(`Unknown global "${second}"`, 404);
     if (third !== void 0) return globalAction(cms, ctx, method, second, segments.slice(2));
-    if (method === "GET")
+    if (method === "GET") {
+      if (ctx.url.searchParams.has("preview")) {
+        requirePreview(cms, ctx, { global: second });
+        return {
+          body: await cms.findGlobal(second, {
+            ...parseDepth(ctx.url),
+            ...parseLocale(ctx.url),
+            draft: true
+          })
+        };
+      }
       return { body: await cms.findGlobal(second, { ...access, ...parseDepth(ctx.url), draft }) };
+    }
     if (method === "POST") {
       const body = await readJson(ctx.request);
       return { body: await cms.updateGlobal(second, body, { ...access, ...parseDepth(ctx.url) }) };
@@ -2792,6 +3281,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);
@@ -2807,6 +3303,16 @@ async function route(cms, ctx, method, segments, options) {
     throw methodNotAllowed(ctx, "GET, POST");
   }
   const id = second;
+  if (method === "GET" && ctx.url.searchParams.has("preview")) {
+    requirePreview(cms, ctx, { collection: collection2, id });
+    const doc = await cms.findById(collection2, id, {
+      ...parseDepth(ctx.url),
+      ...parseLocale(ctx.url),
+      draft: true
+    });
+    if (!doc) throw new NotFoundError(collection2, id);
+    return { body: doc };
+  }
   if (method === "GET") {
     const doc = await cms.findById(collection2, id, { ...access, ...parseDepth(ctx.url), draft });
     if (!doc) throw new NotFoundError(collection2, id);
@@ -2826,7 +3332,7 @@ async function route(cms, ctx, method, segments, options) {
   throw methodNotAllowed(ctx, "GET, PATCH, DELETE");
 }
 async function documentAction(cms, ctx, method, collection2, id, path) {
-  const access = { overrideAccess: false, user: ctx.user };
+  const access = { overrideAccess: false, user: ctx.user, ...parseLocale(ctx.url) };
   const depth = parseDepth(ctx.url);
   const [action, versionId, extra] = path;
   if (action === "versions" && versionId === void 0) {
@@ -2843,6 +3349,13 @@ 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);
+    const result = await cms.preview(collection2, id, body, { ...access, ...depth });
+    const token = cms.createPreviewToken({ collection: collection2, id });
+    return { body: { ...result, url: result.url && withPreviewToken(result.url, token) } };
+  }
   if (path.length === 1 && (action === "unpublish" || action === "discard-draft")) {
     if (method !== "POST") throw methodNotAllowed(ctx, "POST");
     const options = { ...access, ...depth };
@@ -2853,7 +3366,7 @@ async function documentAction(cms, ctx, method, collection2, id, path) {
   throw new HttpError("Not found", 404);
 }
 async function globalAction(cms, ctx, method, slug, path) {
-  const access = { overrideAccess: false, user: ctx.user };
+  const access = { overrideAccess: false, user: ctx.user, ...parseLocale(ctx.url) };
   const depth = parseDepth(ctx.url);
   const [action, versionId, extra] = path;
   if (action === "versions" && versionId === void 0) {
@@ -2870,6 +3383,13 @@ 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);
+    const result = await cms.previewGlobal(slug, body, { ...access, ...depth });
+    const token = cms.createPreviewToken({ global: slug });
+    return { body: { ...result, url: result.url && withPreviewToken(result.url, token) } };
+  }
   if (path.length === 1 && (action === "unpublish" || action === "discard-draft")) {
     if (method !== "POST") throw methodNotAllowed(ctx, "POST");
     const options = { ...access, ...depth };
@@ -2879,6 +3399,26 @@ async function globalAction(cms, ctx, method, slug, path) {
   }
   throw new HttpError("Not found", 404);
 }
+function parseLocale(url) {
+  const locale = url.searchParams.get("locale");
+  const fallback = url.searchParams.get("fallback-locale");
+  return {
+    ...locale ? { locale } : {},
+    ...fallback === "false" || fallback === "true" ? { fallbackLocale: fallback === "true" } : {}
+  };
+}
+var PREVIEW_PARAM = "easy-cms-preview";
+function withPreviewToken(url, token) {
+  const hash = url.indexOf("#");
+  const [base, fragment] = hash === -1 ? [url, ""] : [url.slice(0, hash), url.slice(hash)];
+  const separator = base.includes("?") ? "&" : "?";
+  return `${base}${separator}${PREVIEW_PARAM}=${encodeURIComponent(token)}${fragment}`;
+}
+function requirePreview(cms, ctx, target) {
+  const opened = cms.verifyPreviewToken(ctx.url.searchParams.get("preview"));
+  const matches = opened !== null && ("global" in target ? "global" in opened && opened.global === target.global : "collection" in opened && opened.collection === target.collection && opened.id === target.id);
+  if (!matches) throw new UnauthorizedError("Invalid or expired preview token");
+}
 function parsePage(url) {
   const { page, limit } = parseListQuery(url);
   return { page, limit };

package/dist/live-preview.d.ts

@@ -0,0 +1,40 @@
+/** 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[];
+}
+/** Query parameter with the preview token that the admin adds to preview URLs. */
+declare const PREVIEW_PARAM = "easy-cms-preview";
+/**
+ * The preview token from the page URL, or `null`. Pass it on to read the document's draft
+ * without a login, e.g. `fetch(\`${api}/posts/${id}?preview=${token}&depth=2\`)`.
+ */
+declare function getPreviewToken(): string | null;
+/** 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, PREVIEW_PARAM, READY_MESSAGE, getPreviewToken, isLivePreview, subscribeLivePreview };

package/dist/live-preview.js

@@ -0,0 +1,31 @@
+// src/live-preview.ts
+var READY_MESSAGE = "easy-cms:preview-ready";
+var PREVIEW_PARAM = "easy-cms-preview";
+function getPreviewToken() {
+  if (typeof window === "undefined") return null;
+  return new URLSearchParams(window.location.search).get(PREVIEW_PARAM);
+}
+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 {
+  PREVIEW_PARAM,
+  READY_MESSAGE,
+  getPreviewToken,
+  isLivePreview,
+  subscribeLivePreview
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easy-cms/core",
-  "version": "0.3.0",
+  "version": "0.5.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": [