@payload-onpage/plugin 0.2.1 → 0.3.1

package/src/index.ts

@@ -9,8 +9,15 @@
  * Payload's REST API, so access control, hooks, validation, drafts and versions
  * apply unchanged.
  */
-import { DEFAULTS, type SchemaField } from '@payload-onpage/core'
-import type { CollectionConfig, Config, GlobalConfig, Plugin } from 'payload'
+import { DEFAULTS, type DocRef, type SchemaField } from '@payload-onpage/core'
+import {
+  InvalidConfiguration,
+  type CollectionConfig,
+  type Config,
+  type GlobalConfig,
+  type Plugin,
+} from 'payload'
+import { deepMergeSimple } from 'payload/shared'
 import { createEndpoints } from './endpoints.ts'
 import { encodeOnRead, guardStaleWrite, stripMarkers } from './hooks.ts'
 import { normalizeEntries, type Entry, type OnPageOptions } from './options.ts'
@@ -19,56 +26,73 @@ import { translations } from './translations.ts'
 
 const APPLIED = 'payload-onpage'
 
-type Translations = Record<string, Record<string, unknown>>
-/** Ours first; the site's own translations (any language, any key) win. */
-function mergeTranslations(
-  ours: Translations,
-  theirs: unknown,
-): NonNullable<Config['i18n']>['translations'] {
-  const out: Translations = { ...ours }
-  for (const [lang, table] of Object.entries((theirs ?? {}) as Translations)) {
-    const mine = out[lang] ?? {}
-    out[lang] = {
-      ...mine,
-      ...table,
-      onpage: { ...(mine.onpage as object), ...(table.onpage ?? {}) },
-    }
-  }
-  return out
-}
-
 export function onpage(options: OnPageOptions): Plugin {
   return (incoming: Config): Config => {
     if (options.enabled === false || incoming.custom?.[APPLIED]) return incoming
+    const { session } = options
+    if (!session)
+      throw new InvalidConfiguration(
+        'payload-onpage: pass `session` (e.g. nextSession() from @payload-onpage/next/session). The enter, mode, exit and preview endpoints need it.',
+      )
     const prefix = options.routePrefix ?? DEFAULTS.routePrefix
-    const apiRoute = incoming.routes?.api ?? DEFAULTS.apiRoute
-    const entries = [
-      ...normalizeEntries(options.collections, 'collection'),
-      ...normalizeEntries(options.globals, 'global'),
-    ]
-    const byKey = new Map(entries.map((e) => [`${e.kind}:${e.slug}`, e]))
+    const entries = normalizeEntries(options)
+    const keyOf = (kind: DocRef['kind'], slug: string) => `${kind}:${slug}`
+    const byKey = new Map(entries.map((e) => [keyOf(e.kind, e.slug), e]))
 
-    const withHooks = <T extends CollectionConfig | GlobalConfig>(cfg: T, entry: Entry): T => {
+    const missing = entries.filter((e) =>
+      e.kind === 'global'
+        ? !incoming.globals?.some((g) => g.slug === e.slug)
+        : !incoming.collections?.some((c) => c.slug === e.slug),
+    )
+    if (missing.length) {
+      throw new InvalidConfiguration(
+        `payload-onpage: unknown ${missing.map((e) => `${e.kind} "${e.slug}"`).join(', ')}`,
+      )
+    }
+
+    /** The hooks every enabled document gets (see ./hooks). Encoding serializes the fields once, lazily. */
+    const hooksFor = (cfg: CollectionConfig | GlobalConfig, entry: Entry) => {
       let fields: SchemaField[] | undefined
-      // Encoding only needs names, types and editors: serialize once, lazily, without request context.
-      const lazyFields = () => (fields ??= serializeFields(cfg.fields, { blocks: incoming.blocks }))
-      const hooks = { ...(cfg.hooks ?? {}) } as Record<string, unknown[]>
-      hooks.beforeValidate = [...(hooks.beforeValidate ?? []), stripMarkers]
-      hooks.beforeChange = [...(hooks.beforeChange ?? []), stripMarkers, guardStaleWrite]
-      hooks.afterRead = [
-        ...(hooks.afterRead ?? []),
-        encodeOnRead({
-          kind: entry.kind,
-          slug: cfg.slug,
-          fields: lazyFields,
-          only: entry.options.fields,
-          filter: options.encode,
-        }),
-      ]
-      return { ...cfg, hooks }
+      return {
+        beforeValidate: [stripMarkers],
+        beforeChange: [stripMarkers, guardStaleWrite],
+        afterRead: [
+          encodeOnRead({
+            kind: entry.kind,
+            slug: cfg.slug,
+            fields: () => (fields ??= serializeFields(cfg.fields, { blocks: incoming.blocks })),
+            ...(entry.options.fields ? { only: entry.options.fields } : {}),
+            ...(options.encode ? { filter: options.encode } : {}),
+          }),
+        ],
+      }
+    }
+    const withCollectionHooks = (c: CollectionConfig, entry: Entry): CollectionConfig => {
+      const add = hooksFor(c, entry)
+      return {
+        ...c,
+        hooks: {
+          ...c.hooks,
+          beforeValidate: [...(c.hooks?.beforeValidate ?? []), ...add.beforeValidate],
+          beforeChange: [...(c.hooks?.beforeChange ?? []), ...add.beforeChange],
+          afterRead: [...(c.hooks?.afterRead ?? []), ...add.afterRead],
+        },
+      }
+    }
+    const withGlobalHooks = (g: GlobalConfig, entry: Entry): GlobalConfig => {
+      const add = hooksFor(g, entry)
+      return {
+        ...g,
+        hooks: {
+          ...g.hooks,
+          beforeValidate: [...(g.hooks?.beforeValidate ?? []), ...add.beforeValidate],
+          beforeChange: [...(g.hooks?.beforeChange ?? []), ...add.beforeChange],
+          afterRead: [...(g.hooks?.afterRead ?? []), ...add.afterRead],
+        },
+      }
     }
 
-    const control = (kind: Entry['kind'], slug: string) => ({
+    const control = (kind: DocRef['kind'], slug: string) => ({
       path: '@payload-onpage/plugin/admin#OnPageAdminControls',
       clientProps: { kind, slug, prefix },
     })
@@ -112,39 +136,28 @@ export function onpage(options: OnPageOptions): Plugin {
       }
     }
 
-    const missing = entries.filter((e) =>
-      e.kind === 'global'
-        ? !incoming.globals?.some((g) => g.slug === e.slug)
-        : !incoming.collections?.some((c) => c.slug === e.slug),
-    )
-    if (missing.length) {
-      throw new Error(
-        `payload-onpage: unknown ${missing.map((e) => `${e.kind} "${e.slug}"`).join(', ')}`,
-      )
-    }
-
     return {
       ...incoming,
       custom: { ...incoming.custom, [APPLIED]: true },
       i18n: {
         ...incoming.i18n,
-        translations: mergeTranslations(translations, incoming.i18n?.translations),
+        // Ours first; the site's own translations (any language, any key) win.
+        translations: deepMergeSimple(translations, incoming.i18n?.translations ?? {}),
       },
       collections: (incoming.collections ?? []).map((c) => {
-        const entry = byKey.get(`collection:${c.slug}`)
-        return entry ? withCollectionAdmin(withHooks(c, entry)) : c
+        const entry = byKey.get(keyOf('collection', c.slug))
+        return entry ? withCollectionAdmin(withCollectionHooks(c, entry)) : c
       }),
       globals: (incoming.globals ?? []).map((g) => {
-        const entry = byKey.get(`global:${g.slug}`)
-        return entry ? withGlobalAdmin(withHooks(g, entry)) : g
+        const entry = byKey.get(keyOf('global', g.slug))
+        return entry ? withGlobalAdmin(withGlobalHooks(g, entry)) : g
       }),
       endpoints: [
         ...(incoming.endpoints ?? []),
         ...createEndpoints({
-          options,
+          options: { ...options, session },
           prefix,
-          apiRoute,
-          entry: (kind, slug) => byKey.get(`${kind}:${slug}`),
+          entry: (kind, slug) => byKey.get(keyOf(kind, slug)),
         }),
       ],
       onInit: async (payload) => {
@@ -159,7 +172,7 @@ export function onpage(options: OnPageOptions): Plugin {
   }
 }
 
-export type { OnPageDocOptions, OnPageOptions } from './options.ts'
+export type { OnPageDocOptions, OnPageOptions, OnPageTargets } from './options.ts'
 export { canEditDocument, canUseOnPage } from './access.ts'
 export { createPreviewToken, verifyPreviewToken, type PreviewTokenPayload } from './tokens.ts'
 export { serializeFields, type SerializeContext } from './schema.ts'

package/src/options.ts

@@ -1,5 +1,5 @@
 import type { DocRef, EncodeFilter, SessionAdapter } from '@payload-onpage/core'
-import type { PayloadRequest } from 'payload'
+import type { CollectionSlug, GlobalSlug, PayloadRequest } from 'payload'
 
 export interface OnPageDocOptions {
   /** Top-level fields editable on the page. Default: every top-level field the user may update. */
@@ -10,21 +10,29 @@ export interface OnPageDocOptions {
    */
   url?: (args: {
     doc: Record<string, unknown>
-    locale?: string
+    locale?: string | undefined
     req: PayloadRequest
   }) => string | null | Promise<string | null>
 }
 
+/**
+ * Collections or globals to enable: a list of slugs, or slugs mapped to options.
+ * Slugs are checked against your generated Payload types (`CollectionSlug` /
+ * `GlobalSlug`), so a typo is a compile error.
+ */
+export type OnPageTargets<Slug extends string> =
+  Slug[] | Partial<Record<Slug, OnPageDocOptions | true>>
+
 export interface OnPageOptions {
-  collections?: string[] | Record<string, OnPageDocOptions | true>
-  globals?: string[] | Record<string, OnPageDocOptions | true>
+  collections?: OnPageTargets<CollectionSlug>
+  globals?: OnPageTargets<GlobalSlug>
   /**
    * Who may use on-page editing (`ref` undefined) and edit a given document.
    * Default: users of the admin user collection, with the document's own
    * `update` access (evaluated by Payload, including row-level rules).
    */
   access?: (args: { req: PayloadRequest; ref?: DocRef }) => boolean | Promise<boolean>
-  /** Framework adapter that switches edit/preview mode (e.g. `nextSession()`). Required for the enter/exit/preview endpoints. */
+  /** Framework adapter that switches edit/preview mode (e.g. `nextSession()`). Required for the enter/mode/exit/preview endpoints. */
   session?: SessionAdapter
   /** Narrow which strings get auto-mapping markers. */
   encode?: EncodeFilter
@@ -46,20 +54,24 @@ export interface OnPageOptions {
   /** Auth cookie an editor's session is bound to. Default `${cookiePrefix}-token` ("payload-token"). */
   authCookie?: string
   /** Endpoint prefix under the API route. Default "/onpage". */
-  routePrefix?: string
+  routePrefix?: `/${string}`
   enabled?: boolean
 }
 
-export interface Entry {
-  kind: 'collection' | 'global'
-  slug: string
-  options: OnPageDocOptions
+/** One enabled collection or global, with its slug typed by kind. */
+export type Entry =
+  | { kind: 'collection'; slug: CollectionSlug; options: OnPageDocOptions }
+  | { kind: 'global'; slug: GlobalSlug; options: OnPageDocOptions }
+
+function entriesOf<Slug extends string>(input: OnPageTargets<Slug> | undefined) {
+  return Array.isArray(input)
+    ? input.map((slug) => ({ slug, options: {} }))
+    : (Object.entries(input ?? {}) as Array<[Slug, OnPageDocOptions | true | undefined]>)
+        .filter(([, o]) => o !== undefined)
+        .map(([slug, o]) => ({ slug, options: o === true || !o ? {} : o }))
 }
 
-export const normalizeEntries = (
-  input: OnPageOptions['collections'],
-  kind: Entry['kind'],
-): Entry[] =>
-  Array.isArray(input)
-    ? input.map((slug) => ({ kind, slug, options: {} }))
-    : Object.entries(input ?? {}).map(([slug, o]) => ({ kind, slug, options: o === true ? {} : o }))
+export const normalizeEntries = (options: OnPageOptions): Entry[] => [
+  ...entriesOf(options.collections).map((e) => ({ kind: 'collection' as const, ...e })),
+  ...entriesOf(options.globals).map((e) => ({ kind: 'global' as const, ...e })),
+]

package/src/paths.ts

@@ -1,6 +1,6 @@
 /** Where a document lives on the site. */
 import { safePath, type DocRef } from '@payload-onpage/core'
-import type { PayloadRequest } from 'payload'
+import type { PayloadRequest, TypedLocale } from 'payload'
 import { originOf } from './http.ts'
 import type { Entry } from './options.ts'
 
@@ -13,36 +13,23 @@ export async function resolvePath(
   req: PayloadRequest,
   ref: DocRef,
   entry: Entry,
-  locale?: string,
+  locale?: TypedLocale,
 ): 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)
+  const read = { draft: true, depth: 0, overrideAccess: true, ...(locale ? { locale } : {}) }
+  const doc: Record<string, unknown> | null =
+    entry.kind === 'global'
+      ? await req.payload.findGlobal({ slug: entry.slug, ...read }).catch(() => null)
+      : ref.kind === 'collection'
+        ? await req.payload
+            .findByID({ collection: entry.slug, id: ref.id, ...read })
+            .catch(() => null)
+        : 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 (entry.options.url) url = await entry.options.url({ doc, locale: locale ?? undefined, req })
+  else if (entry.kind === 'collection') {
+    const preview = req.payload.collections[entry.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 = '/'

package/src/schema.ts

@@ -21,44 +21,45 @@ const SYSTEM_FIELDS = new Set(['id', 'createdAt', 'updatedAt', '_status', 'delet
 /** 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 {
+/**
+ * The properties every data field may have. Payload's `Field` union declares
+ * them per member, so they're read through this one view; everything specific
+ * to a field type is read from Payload's narrowed type in `serializeFields`.
+ */
+interface CommonField {
   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 }
-  }
+  admin?: { description?: unknown; custom?: { onpage?: { editor?: unknown } } }
 }
 
+/** `{ key: n }` when n is a number, else nothing (for spreading optional limits). */
+const num = <K extends string>(key: K, n: unknown): Partial<Record<K, number>> =>
+  typeof n === 'number' ? ({ [key]: n } as Record<K, number>) : {}
+
 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
+  i18n?: I18nLike | undefined
   /** Global blocks (`config.blocks`), to resolve `blockReferences`. */
-  blocks?: Block[]
+  blocks?: Block[] | undefined
   /** Field-level permissions: fields the user can't update are left out. */
-  permissions?: Permissions
+  permissions?: Permissions | undefined
   /** Collects function defaults to evaluate for this request. */
-  defaults?: { req: PayloadRequest; pending: Promise<void>[] }
+  defaults?: { req: PayloadRequest; pending: Promise<void>[] } | undefined
 }
 
-const label = (value: unknown, fallback: string, ctx: SerializeContext): string => {
+/** A config label (string, translations or function) in the request's language, else `fallback`. */
+export const label = (
+  value: unknown,
+  fallback: string,
+  ctx: Pick<SerializeContext, 'i18n'>,
+): string => {
   if (value == null || value === false) return fallback
   if (typeof value === 'string') return value || fallback
   if (!ctx.i18n) return fallback
@@ -160,76 +161,134 @@ export function serializeFields(
     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 = {
+    const common = f as CommonField
+    const base = {
       name: f.name,
-      type: f.type,
-      label: label(anyField.label, toWords(f.name), ctx),
+      label: label(common.label, toWords(f.name), ctx),
+      ...(common.localized ? { localized: true } : {}),
+      ...(common.required ? { required: true } : {}),
+    }
+    const description = label(common.admin?.description, '', ctx)
+    const editor = common.admin?.custom?.onpage?.editor ?? common.custom?.onpage?.editor
+    const childCtx = { ...ctx, permissions: perms }
+    const rows = (
+      labels: { singular?: unknown; plural?: unknown } | undefined,
+      min: unknown,
+      max: unknown,
+    ) => {
+      const fallback = formatLabels(f.name)
+      return {
+        labels: {
+          singular: label(labels?.singular, fallback.singular, ctx),
+          plural: label(labels?.plural, fallback.plural, ctx),
+        },
+        ...num('minRows', min),
+        ...num('maxRows', max),
+      }
+    }
+
+    let field: SchemaField
+    switch (f.type) {
+      case 'text':
+      case 'textarea':
+      case 'email':
+      case 'code':
+      case 'json':
+      case 'checkbox':
+      case 'point':
+      case 'richText':
+        field = { ...base, type: f.type, ...('hasMany' in f && f.hasMany ? { hasMany: true } : {}) }
+        break
+      case 'number':
+        field = {
+          ...base,
+          type: 'number',
+          ...(f.hasMany ? { hasMany: true } : {}),
+          ...num('min', f.min),
+          ...num('max', f.max),
+        }
+        break
+      case 'date': {
+        const picker = f.admin?.date?.pickerAppearance
+        field = {
+          ...base,
+          type: 'date',
+          ...(typeof picker === 'string' ? { pickerAppearance: picker } : {}),
+        }
+        break
+      }
+      case 'select':
+      case 'radio':
+        field = {
+          ...base,
+          type: f.type,
+          options: f.options.map((o) =>
+            typeof o === 'string'
+              ? { label: o, value: o }
+              : { label: label(o.label, String(o.value), ctx), value: String(o.value) },
+          ),
+          ...('hasMany' in f && f.hasMany ? { hasMany: true } : {}),
+        }
+        break
+      case 'relationship':
+      case 'upload':
+        field = {
+          ...base,
+          type: f.type,
+          relationTo: f.relationTo,
+          ...(f.hasMany ? { hasMany: true } : {}),
+        }
+        break
+      case 'group':
+        field = { ...base, type: 'group', fields: serializeFields(f.fields, childCtx) }
+        break
+      case 'array':
+        field = {
+          ...base,
+          type: 'array',
+          fields: serializeFields(f.fields, childCtx),
+          ...rows(f.labels, f.minRows, f.maxRows),
+        }
+        break
+      case '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 = {
+          ...base,
+          type: 'blocks',
+          blocks: [...f.blocks, ...refs].map((b) =>
+            serializeBlock(b, blockPermissions(ctx.permissions, f.name, b.slug), ctx),
+          ),
+          ...rows(f.labels, f.minRows, f.maxRows),
+        }
+        break
+      }
+      default:
+        // join/ui are skipped above; anything newer than this plugin isn't editable on the page.
+        continue
     }
-    if (anyField.localized) field.localized = true
-    if (anyField.required) field.required = true
-    if (anyField.hasMany) field.hasMany = true
-    if (typeof anyField.defaultValue === 'function') {
+    if (description) field.description = description
+    if (typeof editor === 'string') field.editor = editor
+    if (typeof common.defaultValue === 'function') {
       if (ctx.defaults) {
         const { req, pending } = ctx.defaults
+        const target = field
         pending.push(
           getDefaultValue({
-            defaultValue: anyField.defaultValue,
+            defaultValue: common.defaultValue,
             locale: req.locale ?? undefined,
             req,
             user: req.user,
           })
             .then((v) => {
-              if (isJsonSafe(v)) field.defaultValue = v
+              if (isJsonSafe(v)) target.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),
-      )
+    } else if (isJsonSafe(common.defaultValue)) {
+      field.defaultValue = common.defaultValue
     }
     out.push(field)
   }
@@ -239,11 +298,10 @@ export function serializeFields(
 /** 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) {
+    if (f.type === 'relationship' || f.type === 'upload')
       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)
+    if (f.type === 'group' || f.type === 'array') relationTargets(f.fields, into)
+    if (f.type === 'blocks') for (const b of f.blocks) relationTargets(b.fields, into)
   }
   return into
 }

package/src/translations.ts

@@ -1,18 +1,24 @@
+import type { NestedKeysStripped } from '@payloadcms/translations'
 /**
  * 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}}",
-    },
+const 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}}",
   },
+}
+
+/** Every language must translate every key: a missing or extra one is a compile error. */
+type Table = { onpage: Record<keyof (typeof en)['onpage'], string> }
+
+export const translations = {
+  en,
   es: {
     onpage: {
       editOnPage: 'Editar en la página',
@@ -40,6 +46,6 @@ export const translations = {
       linkFailed: 'Vorschaulink konnte nicht erstellt werden: {{message}}',
     },
   },
-}
+} satisfies Record<string, Table>
 
-export type OnPageTranslationKey = `onpage:${keyof (typeof translations)['en']['onpage']}`
+export type OnPageTranslationKey = NestedKeysStripped<typeof en>