@payload-onpage/plugin 0.0.0-stage → 0.1.0

package/src/paths.ts

@@ -0,0 +1,59 @@
+/** Where a document lives on the site. */
+import { safePath, type DocRef } from '@payload-onpage/core'
+import type { PayloadRequest } from 'payload'
+import { originOf } from './http.ts'
+import type { Entry } from './options.ts'
+
+/**
+ * The site path that shows a document: the entry's `url` option, else the
+ * collection's `admin.preview` URL, else `/<slug>`; globals default to "/".
+ * Absolute URLs must be same-origin. Returns null when there's no page.
+ */
+export async function resolvePath(
+  req: PayloadRequest,
+  ref: DocRef,
+  entry: Entry,
+  locale?: string,
+): Promise<string | null> {
+  const localeArg = locale ? { locale: locale as never } : {}
+  const doc =
+    ref.kind === 'global'
+      ? await req.payload
+          .findGlobal({
+            slug: ref.slug as never,
+            draft: true,
+            depth: 0,
+            overrideAccess: true,
+            ...localeArg,
+          })
+          .catch(() => null)
+      : await req.payload
+          .findByID({
+            collection: ref.slug as never,
+            id: ref.id,
+            draft: true,
+            depth: 0,
+            overrideAccess: true,
+            ...localeArg,
+          })
+          .catch(() => null)
+  if (!doc) return null
+
+  let url: string | null | undefined
+  if (entry.options.url) url = await entry.options.url({ doc, locale, req })
+  else if (ref.kind === 'collection') {
+    const preview = req.payload.collections[ref.slug]?.config.admin?.preview
+    if (preview) url = await preview(doc, { locale: locale ?? '', req, token: null })
+    if (!url && typeof doc.slug === 'string') url = `/${doc.slug.replace(/^\/+/, '')}`
+  } else url = '/'
+  if (!url) return null
+
+  const origin = originOf(req)
+  try {
+    const u = new URL(url, origin)
+    if (u.origin !== origin) return null
+    return safePath(u.pathname + u.search)
+  } catch {
+    return null
+  }
+}

package/src/schema.ts

@@ -0,0 +1,251 @@
+/**
+ * Builds the editor's JSON schema from Payload field configs, using Payload's
+ * own field predicates and translations. Payload's client config can't be used
+ * instead: it strips `defaultValue` and `custom`, which the editor needs.
+ */
+import { getTranslation } from '@payloadcms/translations'
+import type { DocumentSchema, SchemaBlock, SchemaField } from '@payload-onpage/core'
+import type { Block, Field, PayloadRequest, SanitizedFieldsPermissions } from 'payload'
+import { getDefaultValue } from 'payload'
+import {
+  fieldAffectsData,
+  fieldIsHiddenOrDisabled,
+  fieldIsVirtual,
+  tabHasName,
+  formatLabels,
+  toWords,
+} from 'payload/shared'
+
+/** Fields Payload manages itself; never editable on the page. */
+const SYSTEM_FIELDS = new Set(['id', 'createdAt', 'updatedAt', '_status', 'deletedAt'])
+/** Data fields with no meaningful on-page value. */
+const SKIP_TYPES = new Set(['join', 'ui'])
+
+/** The optional, type-specific field properties the serializer reads. */
+interface LooseField {
+  label?: unknown
+  labels?: { singular?: unknown; plural?: unknown }
+  localized?: boolean
+  required?: boolean
+  hasMany?: boolean
+  defaultValue?: unknown
+  options?: unknown[]
+  relationTo?: string | string[]
+  minRows?: number
+  maxRows?: number
+  min?: number
+  max?: number
+  custom?: { onpage?: { editor?: unknown } }
+  admin?: {
+    description?: unknown
+    custom?: { onpage?: { editor?: unknown } }
+    date?: { pickerAppearance?: unknown }
+  }
+}
+
+type I18nLike = Parameters<typeof getTranslation>[1]
+type AnyLabel = Parameters<typeof getTranslation>[0]
+type Permissions = SanitizedFieldsPermissions | undefined
+
+export interface SerializeContext {
+  /** Translates labels into the admin language. Without it, plain-string labels or the field name are used. */
+  i18n?: I18nLike
+  /** Global blocks (`config.blocks`), to resolve `blockReferences`. */
+  blocks?: Block[]
+  /** Field-level permissions: fields the user can't update are left out. */
+  permissions?: Permissions
+  /** Collects function defaults to evaluate for this request. */
+  defaults?: { req: PayloadRequest; pending: Promise<void>[] }
+}
+
+const label = (value: unknown, fallback: string, ctx: SerializeContext): string => {
+  if (value == null || value === false) return fallback
+  if (typeof value === 'string') return value || fallback
+  if (!ctx.i18n) return fallback
+  try {
+    const out = getTranslation(value as AnyLabel, ctx.i18n)
+    return typeof out === 'string' && out ? out : fallback
+  } catch {
+    return fallback
+  }
+}
+
+/** Sanitized permissions: `true` = everything; a missing entry = denied. */
+function childPermissions(perms: Permissions, name: string): Permissions | false {
+  if (perms === undefined || perms === true) return perms
+  const entry = perms[name]
+  if (!entry) return false
+  if (entry === true) return true
+  if (entry.update !== true) return false
+  return entry.fields ?? true
+}
+
+function blockPermissions(perms: Permissions, name: string, slug: string): Permissions {
+  if (perms === undefined || perms === true) return perms
+  const entry = perms[name]
+  if (!entry || entry === true) return true
+  const block = (
+    entry.blocks as Record<string, { fields?: Permissions } | true | undefined> | undefined
+  )?.[slug]
+  // No block-level rule: the blocks field's own permission (already checked) applies.
+  if (!block || block === true) return true
+  return block.fields ?? true
+}
+
+const isJsonSafe = (v: unknown): boolean => {
+  if (v === undefined || typeof v === 'function') return false
+  try {
+    JSON.stringify(v)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function serializeBlock(block: Block, perms: Permissions, ctx: SerializeContext): SchemaBlock {
+  return {
+    slug: block.slug,
+    labels: {
+      singular: label(block.labels?.singular, toWords(block.slug), ctx),
+      plural: label(block.labels?.plural, toWords(block.slug), ctx),
+    },
+    fields: serializeFields(block.fields, { ...ctx, permissions: perms }),
+  }
+}
+
+/**
+ * Serialize Payload field configs into the editor schema. Presentational
+ * containers (row, collapsible, unnamed group/tab) are flattened into their
+ * parent; named tabs become groups; hidden, disabled, virtual, system and
+ * join/ui fields are left out.
+ */
+export function serializeFields(
+  fields: Field[] | undefined,
+  ctx: SerializeContext = {},
+): SchemaField[] {
+  const out: SchemaField[] = []
+  for (const f of fields ?? []) {
+    if (!f || typeof f !== 'object' || SKIP_TYPES.has(f.type)) continue
+    if (f.type === 'tabs') {
+      for (const tab of f.tabs ?? []) {
+        if (!tabHasName(tab)) {
+          out.push(...serializeFields(tab.fields, ctx))
+          continue
+        }
+        const perms = childPermissions(ctx.permissions, tab.name)
+        if (perms === false) continue
+        out.push({
+          name: tab.name,
+          type: 'group',
+          label: label(tab.label, toWords(tab.name), ctx),
+          fields: serializeFields(tab.fields, { ...ctx, permissions: perms }),
+          ...(tab.localized ? { localized: true } : {}),
+        })
+      }
+      continue
+    }
+    if (!fieldAffectsData(f)) {
+      // row, collapsible, unnamed group: their children belong to the parent.
+      if ('fields' in f && Array.isArray(f.fields)) out.push(...serializeFields(f.fields, ctx))
+      continue
+    }
+    // Hidden from the admin (admin.hidden) or the API (hidden), disabled, virtual: not editable here either.
+    if (
+      SYSTEM_FIELDS.has(f.name) ||
+      fieldIsHiddenOrDisabled(f) ||
+      fieldIsVirtual(f) ||
+      f.admin?.hidden
+    )
+      continue
+    const perms = childPermissions(ctx.permissions, f.name)
+    if (perms === false) continue
+
+    // Field is a large union; read the optional, type-specific properties through one loose view.
+    const anyField = f as unknown as LooseField
+    const field: SchemaField = {
+      name: f.name,
+      type: f.type,
+      label: label(anyField.label, toWords(f.name), ctx),
+    }
+    if (anyField.localized) field.localized = true
+    if (anyField.required) field.required = true
+    if (anyField.hasMany) field.hasMany = true
+    if (typeof anyField.defaultValue === 'function') {
+      if (ctx.defaults) {
+        const { req, pending } = ctx.defaults
+        pending.push(
+          getDefaultValue({
+            defaultValue: anyField.defaultValue,
+            locale: req.locale ?? undefined,
+            req,
+            user: req.user,
+          })
+            .then((v) => {
+              if (isJsonSafe(v)) field.defaultValue = v
+            })
+            .catch(() => undefined),
+        )
+      }
+    } else if (isJsonSafe(anyField.defaultValue)) {
+      field.defaultValue = anyField.defaultValue
+    }
+    const description = label(anyField.admin?.description, '', ctx)
+    if (description) field.description = description
+    if (Array.isArray(anyField.options)) {
+      field.options = anyField.options.map((o: unknown) =>
+        typeof o === 'string'
+          ? { label: o, value: o }
+          : {
+              label: label(
+                (o as { label?: unknown }).label,
+                String((o as { value: unknown }).value),
+                ctx,
+              ),
+              value: String((o as { value: unknown }).value),
+            },
+      )
+    }
+    if (anyField.relationTo) field.relationTo = anyField.relationTo
+    for (const k of ['minRows', 'maxRows', 'min', 'max'] as const) {
+      const n = anyField[k]
+      if (typeof n === 'number') field[k] = n
+    }
+    const editor = anyField.admin?.custom?.onpage?.editor ?? anyField.custom?.onpage?.editor
+    if (typeof editor === 'string') field.editor = editor
+    const picker = anyField.admin?.date?.pickerAppearance
+    if (typeof picker === 'string') field.pickerAppearance = picker
+    const childCtx = { ...ctx, permissions: perms }
+    if (f.type === 'group' || f.type === 'array') field.fields = serializeFields(f.fields, childCtx)
+    if (f.type === 'array') {
+      const fallback = formatLabels(f.name)
+      field.labels = {
+        singular: label(anyField.labels?.singular, fallback.singular, ctx),
+        plural: label(anyField.labels?.plural, fallback.plural, ctx),
+      }
+    }
+    if (f.type === 'blocks') {
+      const refs = (f.blockReferences ?? [])
+        .map((b) => (typeof b === 'string' ? ctx.blocks?.find((x) => x.slug === b) : b))
+        .filter((b): b is Block => !!b)
+      field.blocks = [...(f.blocks ?? []), ...refs].map((b) =>
+        serializeBlock(b, blockPermissions(ctx.permissions, f.name, b.slug), ctx),
+      )
+    }
+    out.push(field)
+  }
+  return out
+}
+
+/** Every collection a relationship or upload field in `fields` points to. */
+export function relationTargets(fields: SchemaField[], into = new Set<string>()): Set<string> {
+  for (const f of fields) {
+    if ((f.type === 'relationship' || f.type === 'upload') && f.relationTo) {
+      for (const slug of Array.isArray(f.relationTo) ? f.relationTo : [f.relationTo]) into.add(slug)
+    }
+    if (f.fields) relationTargets(f.fields, into)
+    for (const b of f.blocks ?? []) relationTargets(b.fields, into)
+  }
+  return into
+}
+
+export type { DocumentSchema }

package/src/tokens.ts

@@ -0,0 +1,46 @@
+/**
+ * Preview-link tokens: sealed (AES-GCM) and expiring, bound to one document
+ * and path. Opaque to the holder, so the link reveals nothing about the draft.
+ */
+import { SEAL_PURPOSE, seal, unseal } from '@payload-onpage/core'
+
+export interface PreviewTokenPayload {
+  /** refKey of the shared document */
+  ref: string
+  /** Site path the link opens. */
+  path: string
+  locale?: string
+  /** Issued at / expires at, seconds since epoch. */
+  iat: number
+  exp: number
+  /** Unique id, for audit logs and revocation lists. */
+  jti: string
+}
+
+export async function createPreviewToken(
+  payload: Pick<PreviewTokenPayload, 'ref' | 'path' | 'locale'>,
+  secret: string,
+  ttlSeconds: number,
+  now = Date.now(),
+): Promise<{ token: string; payload: PreviewTokenPayload }> {
+  const iat = Math.floor(now / 1000)
+  const full: PreviewTokenPayload = {
+    ...payload,
+    iat,
+    exp: iat + ttlSeconds,
+    jti: crypto.randomUUID(),
+  }
+  return { token: await seal(full, secret, SEAL_PURPOSE.previewLink), payload: full }
+}
+
+export async function verifyPreviewToken(
+  token: string,
+  secret: string,
+  now = Date.now(),
+): Promise<PreviewTokenPayload | null> {
+  const p = await unseal<PreviewTokenPayload>(token, secret, SEAL_PURPOSE.previewLink)
+  if (!p || typeof p.exp !== 'number' || p.exp * 1000 <= now) return null
+  if (typeof p.path !== 'string' || typeof p.ref !== 'string' || typeof p.jti !== 'string')
+    return null
+  return p
+}

package/src/translations.ts

@@ -0,0 +1,45 @@
+/**
+ * Admin UI strings, registered with Payload's i18n under the `onpage` namespace
+ * (so the admin language applies). Add or override languages with
+ * `i18n.translations` in your Payload config.
+ */
+export const translations = {
+  en: {
+    onpage: {
+      editOnPage: 'Edit on page',
+      copyPreviewLink: 'Copy preview link',
+      copyPreviewLinkHint: 'Copy a read-only link to this draft',
+      linkCopied: 'Preview link copied — valid until {{date}}',
+      linkFailed: "Couldn't create a preview link: {{message}}",
+    },
+  },
+  es: {
+    onpage: {
+      editOnPage: 'Editar en la página',
+      copyPreviewLink: 'Copiar enlace de vista previa',
+      copyPreviewLinkHint: 'Copiar un enlace de solo lectura a este borrador',
+      linkCopied: 'Enlace copiado: válido hasta {{date}}',
+      linkFailed: 'No se pudo crear el enlace: {{message}}',
+    },
+  },
+  fr: {
+    onpage: {
+      editOnPage: 'Modifier sur la page',
+      copyPreviewLink: 'Copier le lien d’aperçu',
+      copyPreviewLinkHint: 'Copier un lien en lecture seule vers ce brouillon',
+      linkCopied: 'Lien copié — valide jusqu’au {{date}}',
+      linkFailed: 'Impossible de créer le lien : {{message}}',
+    },
+  },
+  de: {
+    onpage: {
+      editOnPage: 'Auf der Seite bearbeiten',
+      copyPreviewLink: 'Vorschaulink kopieren',
+      copyPreviewLinkHint: 'Einen schreibgeschützten Link zu diesem Entwurf kopieren',
+      linkCopied: 'Vorschaulink kopiert – gültig bis {{date}}',
+      linkFailed: 'Vorschaulink konnte nicht erstellt werden: {{message}}',
+    },
+  },
+}
+
+export type OnPageTranslationKey = `onpage:${keyof (typeof translations)['en']['onpage']}`