@payload-onpage/core 0.2.0 → 0.3.0

package/src/path.ts

@@ -5,23 +5,34 @@
 
 export type PathSegment = string | number
 
+/** "3" in "sections.3.title": a row index. */
+export const isIndexSegment = (segment: string): boolean => /^\d+$/.test(segment)
+
+/** Segments that would reach an object's prototype instead of its own data. */
+const UNSAFE_SEGMENTS: ReadonlySet<PathSegment> = new Set(['__proto__', 'constructor', 'prototype'])
+
 export function parsePath(path: string | PathSegment[]): PathSegment[] {
-  if (Array.isArray(path)) return path
-  return path
-    .split('.')
-    .filter((s) => s !== '')
-    .map((s) => (/^\d+$/.test(s) ? Number(s) : s))
+  const segs = Array.isArray(path)
+    ? path
+    : path
+        .split('.')
+        .filter((s) => s !== '')
+        .map((s) => (isIndexSegment(s) ? Number(s) : s))
+  if (segs.some((s) => UNSAFE_SEGMENTS.has(s)))
+    throw new Error(`Unsupported path: ${segs.join('.')}`)
+  return segs
 }
 
 type Container = Record<string | number, unknown>
 
-export function getAt<T = unknown>(obj: unknown, path: string | PathSegment[]): T | undefined {
+/** The value at `path`, or undefined. Narrow the result where it's used (`Array.isArray`, `typeof`…). */
+export function getAt(obj: unknown, path: string | PathSegment[]): unknown {
   let cur: unknown = obj
   for (const seg of parsePath(path)) {
     if (cur == null || typeof cur !== 'object') return undefined
     cur = (cur as Container)[seg]
   }
-  return cur as T | undefined
+  return cur
 }
 
 /** Returns a copy of `obj` with `value` at `path`; untouched branches are shared. */
@@ -41,7 +52,7 @@ export function updateArray<T>(
   path: string | PathSegment[],
   fn: (arr: unknown[]) => unknown[],
 ): T {
-  const current = getAt<unknown[]>(obj, path)
+  const current = getAt(obj, path)
   return setAt(obj, path, fn(Array.isArray(current) ? current : []))
 }
 
@@ -49,8 +60,7 @@ export function moveItem<T>(arr: T[], from: number, to: number): T[] {
   if (from === to || from < 0 || from >= arr.length) return arr
   const target = Math.max(0, Math.min(arr.length - 1, to))
   const copy = arr.slice()
-  const [item] = copy.splice(from, 1)
-  copy.splice(target, 0, item)
+  copy.splice(target, 0, ...copy.splice(from, 1))
   return copy
 }
 
@@ -75,6 +85,18 @@ export function splitItemPath(path: string): [string, number] | null {
   return [segs.slice(0, -1).join('.'), last]
 }
 
+/**
+ * The rows that enclose a path, outermost first: "sections.2.items.0.title" →
+ * ["sections.2", "sections.2.items.0"]. A path that is itself a row is not included.
+ */
+export function rowPrefixes(path: string): string[] {
+  const segs = path.split('.')
+  const out: string[] = []
+  for (let i = 1; i < segs.length - 1; i++)
+    if (isIndexSegment(segs[i] ?? '')) out.push(segs.slice(0, i + 1).join('.'))
+  return out
+}
+
 /** A 24-hex id, the shape Payload uses for array and block rows. */
 export function newRowId(): string {
   const bytes = new Uint8Array(12)

package/src/payload.ts

@@ -22,7 +22,7 @@ export interface PayloadRestOptions {
   /** API base, default "/api". */
   apiBase?: string
   /** Plugin endpoint prefix, default "/onpage". */
-  prefix?: string
+  prefix?: `/${string}`
   /** Extra request init (headers for a custom auth scheme, etc.). */
   init?: RequestInit
   fetch?: typeof fetch
@@ -51,23 +51,39 @@ export async function errorMessage(res: Response): Promise<string> {
   }
 }
 
-export function payloadRest(opts: PayloadRestOptions = {}): DataSource {
+interface ClientOptions {
+  init?: RequestInit
+  fetch?: typeof fetch
+}
+
+/**
+ * The fetch and request init both adapters use: cookie auth by default, plus the
+ * caller's `init` (custom auth headers…) on every request. Headers are merged
+ * through `Headers`, so a `Headers` instance or tuple list works as well as an object.
+ */
+function client(opts: ClientOptions) {
+  const f = opts.fetch ?? ((...a: Parameters<typeof fetch>) => fetch(...a))
+  const init = (extra: RequestInit = {}): RequestInit => {
+    const headers = new Headers(opts.init?.headers)
+    new Headers(extra.headers).forEach((v, k) => headers.set(k, v))
+    return { credentials: 'include', ...opts.init, ...extra, headers }
+  }
+  return { f, init }
+}
+
+export function payloadRest(
+  opts: PayloadRestOptions = {},
+): DataSource & Required<Pick<DataSource, 'createPreviewLink'>> {
   const api = opts.apiBase ?? DEFAULTS.apiRoute
   const prefix = opts.prefix ?? DEFAULTS.routePrefix
-  const f = opts.fetch ?? ((...a: Parameters<typeof fetch>) => fetch(...a))
-  const init = (extra: RequestInit = {}): RequestInit => ({
-    credentials: 'include',
-    ...opts.init,
-    ...extra,
-    headers: { ...(opts.init?.headers ?? {}), ...(extra.headers ?? {}) },
-  })
+  const { f, init } = client(opts)
   const docUrl = (ref: DocRef) =>
     ref.kind === 'global' ? `${api}/globals/${ref.slug}` : `${api}/${ref.slug}/${ref.id}`
 
   const write = async (
     ref: DocRef,
     data: Doc,
-    o: { locale?: string; updatedAt?: string },
+    o: { locale?: string | undefined; updatedAt?: string | undefined },
     publish: boolean,
   ): Promise<SaveResult> => {
     const query = qs({
@@ -121,7 +137,7 @@ export function payloadRest(opts: PayloadRestOptions = {}): DataSource {
       if (o.locale) p.set('locale', o.locale)
       if (o.query)
         p.set(`where[${titleField}][${titleField === 'id' ? 'equals' : 'like'}]`, o.query)
-      const res = await f(`${api}/${collection}?${p}`, init())
+      const res = await f(`${api}/${collection}?${p}`, init(o.signal ? { signal: o.signal } : {}))
       if (!res.ok) throw new Error(await errorMessage(res))
       const body = (await res.json()) as { docs?: Doc[] }
       return (body.docs ?? []).map((doc) => {
@@ -156,16 +172,30 @@ export function payloadRest(opts: PayloadRestOptions = {}): DataSource {
 export interface PayloadUploadsOptions {
   apiBase?: string
   pageSize?: number
+  /** Extra request init (headers for a custom auth scheme, etc.), as for `payloadRest`. */
+  init?: RequestInit
   fetch?: typeof fetch
 }
 
+/** Smallest image size at least this wide is used for picker thumbnails. */
+const THUMB_WIDTH = 240
+
+/**
+ * A thumbnail URL: Payload's `thumbnailURL` (the collection's adminThumbnail),
+ * else the smallest generated size that is still wide enough, whatever the
+ * sizes are named, else the original.
+ */
 function thumbOf(doc: Doc): string | undefined {
-  const sizes = (doc.sizes ?? {}) as Record<string, { url?: string | null } | undefined>
-  for (const key of ['thumbnail', 'small', 'card', 'medium']) {
-    const u = sizes[key]?.url
-    if (u) return u
-  }
-  return (doc.url as string | undefined) ?? undefined
+  if (typeof doc.thumbnailURL === 'string' && doc.thumbnailURL) return doc.thumbnailURL
+  const sizes = Object.values(
+    (doc.sizes ?? {}) as Record<string, { url?: string | null; width?: number | null } | undefined>,
+  )
+    .filter(
+      (s): s is { url: string; width?: number | null } => typeof s?.url === 'string' && !!s.url,
+    )
+    .sort((a, b) => (a.width ?? Infinity) - (b.width ?? Infinity))
+  const fit = sizes.find((s) => (s.width ?? 0) >= THUMB_WIDTH) ?? sizes.at(-1)
+  return fit?.url ?? (typeof doc.url === 'string' ? doc.url : undefined)
 }
 
 const toItem = (doc: Doc): MediaItem => ({
@@ -177,11 +207,13 @@ const toItem = (doc: Doc): MediaItem => ({
   doc,
 })
 
-export function payloadUploads(opts: PayloadUploadsOptions = {}): MediaLibrary {
+export function payloadUploads(
+  opts: PayloadUploadsOptions = {},
+): MediaLibrary & Required<Pick<MediaLibrary, 'upload'>> {
   const api = opts.apiBase ?? DEFAULTS.apiRoute
-  const f = opts.fetch ?? ((...a: Parameters<typeof fetch>) => fetch(...a))
+  const { f, init } = client(opts)
   return {
-    async search({ query, page = 1, relationTo }) {
+    async search({ query, page = 1, relationTo, signal }) {
       const p = new URLSearchParams({
         depth: '0',
         limit: String(opts.pageSize ?? 30),
@@ -193,7 +225,7 @@ export function payloadUploads(opts: PayloadUploadsOptions = {}): MediaLibrary {
         p.set('where[and][1][or][0][filename][like]', query)
         p.set('where[and][1][or][1][alt][like]', query)
       }
-      const res = await f(`${api}/${relationTo}?${p}`, { credentials: 'include' })
+      const res = await f(`${api}/${relationTo}?${p}`, init(signal ? { signal } : {}))
       if (!res.ok) throw new Error(await errorMessage(res))
       const body = (await res.json()) as { docs?: Doc[]; hasNextPage?: boolean }
       return { items: (body.docs ?? []).map(toItem), hasMore: Boolean(body.hasNextPage) }
@@ -206,11 +238,7 @@ export function payloadUploads(opts: PayloadUploadsOptions = {}): MediaLibrary {
         '_payload',
         JSON.stringify({ alt: alt ?? file.name.replace(/\.[^.]+$/, '').replace(/[-_]+/g, ' ') }),
       )
-      const res = await f(`${api}/${relationTo}`, {
-        method: 'POST',
-        credentials: 'include',
-        body: form,
-      })
+      const res = await f(`${api}/${relationTo}`, init({ method: 'POST', body: form }))
       if (!res.ok) throw new Error(await errorMessage(res))
       return toItem(((await res.json()) as { doc: Doc }).doc)
     },

package/src/ports.ts

@@ -11,42 +11,60 @@
  * Field editors are registered in @payload-onpage/react.
  */
 import type { DocRef } from './docref.ts'
-import type { MarkerKind } from './stega.ts'
+import { MARKER_KINDS } from './stega.ts'
 import type { DocumentSchema } from './schema.ts'
 
 export type Doc = Record<string, unknown>
 
-export interface SaveResult {
-  ok: boolean
-  /** HTTP-like status on failure; 409 means someone else saved first. */
-  status?: number
-  message?: string
-  /** The document's new `updatedAt` after a successful save. */
-  updatedAt?: string
-}
+/** The outcome of a save: success carries the new version, failure its status. */
+export type SaveResult =
+  | {
+      ok: true
+      /** The document's new `updatedAt`. */
+      updatedAt?: string | undefined
+    }
+  | {
+      ok: false
+      /** HTTP-like status: 409 means someone else saved first, 0 a network failure. */
+      status: number
+      message?: string | undefined
+    }
+
+/** Options callers often fill from other optional values, so `undefined` is accepted. */
+type Opt<T> = T | undefined
 
 export interface DataSource {
-  loadSchema(ref: DocRef, opts: { locale?: string }): Promise<DocumentSchema>
-  loadDocument(ref: DocRef, opts: { draft: boolean; locale?: string; depth?: number }): Promise<Doc>
+  loadSchema(ref: DocRef, opts: { locale?: Opt<string> }): Promise<DocumentSchema>
+  loadDocument(
+    ref: DocRef,
+    opts: { draft: boolean; locale?: Opt<string>; depth?: Opt<number> },
+  ): Promise<Doc>
   /** Save fields to the rolling draft. `updatedAt` enables stale-write detection. */
   saveDraft(
     ref: DocRef,
     data: Doc,
-    opts: { locale?: string; updatedAt?: string },
+    opts: { locale?: Opt<string>; updatedAt?: Opt<string> },
   ): Promise<SaveResult>
   /** Make the given values live. */
   publish(
     ref: DocRef,
     data: Doc,
-    opts: { locale?: string; updatedAt?: string },
+    opts: { locale?: Opt<string>; updatedAt?: Opt<string> },
   ): Promise<SaveResult>
   /** Find documents to link to (relationship fields), by their title field. Optional. */
   search?(
     collection: string,
-    opts: { query?: string; titleField?: string; locale?: string; limit?: number },
+    opts: {
+      query?: Opt<string>
+      titleField?: Opt<string>
+      locale?: Opt<string>
+      limit?: Opt<number>
+      /** Aborted when the search is superseded (the user kept typing). */
+      signal?: Opt<AbortSignal>
+    },
   ): Promise<SearchHit[]>
   /** Create a read-only preview link for a document. Optional. */
-  createPreviewLink?(ref: DocRef, opts: { locale?: string }): Promise<PreviewLink>
+  createPreviewLink?(ref: DocRef, opts: { locale?: Opt<string> }): Promise<PreviewLink>
 }
 
 export interface PreviewLink {
@@ -74,11 +92,13 @@ export interface MediaItem {
 
 export interface MediaLibrary {
   search(opts: {
-    query?: string
-    page?: number
+    query?: Opt<string>
+    page?: Opt<number>
     relationTo: string
+    /** Aborted when the search is superseded. */
+    signal?: Opt<AbortSignal>
   }): Promise<{ items: MediaItem[]; hasMore: boolean }>
-  upload?(file: File, opts: { relationTo: string; alt?: string }): Promise<MediaItem>
+  upload?(file: File, opts: { relationTo: string; alt?: Opt<string> }): Promise<MediaItem>
 }
 
 /**
@@ -86,16 +106,21 @@ export interface MediaLibrary {
  * the kinds auto-mapping markers carry; `field` = resolve from the schema), a
  * row of an array/blocks field (`item`), or the element holding a list (`list`).
  */
-export type TargetKind = MarkerKind | 'field' | 'item' | 'list'
+/** What a page element shows: a marker's kind, or an annotation's field / row item / list. */
+export const TARGET_KINDS = [...MARKER_KINDS, 'field', 'item', 'list'] as const
+export type TargetKind = (typeof TARGET_KINDS)[number]
+export const isTargetKind = (value: unknown): value is TargetKind =>
+  (TARGET_KINDS as readonly unknown[]).includes(value)
 
 export interface Target {
   el: Element
   ref: DocRef
   path: string
   kind: TargetKind
-  label?: string
+  label?: Opt<string>
   /** Which locator produced it ("annotation" wins over inferred ones). */
-  source: string
+  /** Which locator found it. */
+  source: 'annotation' | 'stega' | (string & {})
 }
 
 export interface Locator {
@@ -115,7 +140,10 @@ export interface Renderer {
   live: boolean
 }
 
-export type OnPageMode = 'edit' | 'view'
+export const ONPAGE_MODES = ['edit', 'view'] as const
+export type OnPageMode = (typeof ONPAGE_MODES)[number]
+export const isOnPageMode = (value: unknown): value is OnPageMode =>
+  (ONPAGE_MODES as readonly unknown[]).includes(value)
 
 /**
  * Server side: turns a browser's edit/preview access on and off. Framework

package/src/schema.ts

@@ -2,51 +2,134 @@
  * A JSON-safe description of a document's editable fields, produced on the
  * server by the plugin's schema endpoint (`@payload-onpage/plugin`) and consumed
  * by the editor to build settings forms, new rows and save payloads.
+ *
+ * `SchemaField` is a union discriminated on `type`: each kind carries only its
+ * own properties, so `field.options` exists only after checking for a select,
+ * and a `switch (field.type)` can be checked for exhaustiveness.
  */
+import type { DocRef } from './docref.ts'
 
 export interface SchemaOption {
   label: string
   value: string
 }
 
-export interface SchemaField {
+/** Singular and plural names ("Feature" / "Features"). */
+export interface SchemaLabels {
+  singular: string
+  plural: string
+}
+
+/** What every field has. */
+interface FieldBase {
   name: string
-  type: string
   label: string
   localized?: boolean
   required?: boolean
-  hasMany?: boolean
   defaultValue?: unknown
   description?: string
-  options?: SchemaOption[]
-  relationTo?: string | string[]
-  minRows?: number
-  /** array: what one row and many rows are called (\"Feature\" / \"Features\"). */
-  labels?: { singular: string; plural: string }
-  maxRows?: number
-  /** group / array / named tab */
-  fields?: SchemaField[]
-  /** blocks */
-  blocks?: SchemaBlock[]
   /** Field-editor override: `admin.custom.onpage.editor` (e.g. "color"). */
   editor?: string
-  /** Number limits / date picker appearance, when set on the field. */
+}
+
+/** Fields whose value is a scalar or opaque JSON, edited as a whole. */
+export type ScalarFieldType =
+  'text' | 'textarea' | 'email' | 'code' | 'json' | 'checkbox' | 'point' | 'richText'
+
+export interface ScalarField extends FieldBase {
+  type: ScalarFieldType
+  /** A list of values (text/textarea/email with `hasMany`): not edited inline. */
+  hasMany?: boolean
+}
+
+export interface NumberField extends FieldBase {
+  type: 'number'
+  hasMany?: boolean
   min?: number
   max?: number
+}
+
+export interface DateField extends FieldBase {
+  type: 'date'
+  /** Payload's `admin.date.pickerAppearance` ("dayOnly", "dayAndTime"…). */
   pickerAppearance?: string
 }
 
+export interface ChoiceField extends FieldBase {
+  type: 'select' | 'radio'
+  options: SchemaOption[]
+  hasMany?: boolean
+}
+
+export interface RelationField extends FieldBase {
+  type: 'relationship' | 'upload'
+  relationTo: string | string[]
+  hasMany?: boolean
+}
+
+export interface GroupField extends FieldBase {
+  type: 'group'
+  fields: SchemaField[]
+}
+
+interface RowsField extends FieldBase {
+  labels?: SchemaLabels
+  minRows?: number
+  maxRows?: number
+}
+
+export interface ArrayField extends RowsField {
+  type: 'array'
+  fields: SchemaField[]
+}
+
+export interface BlocksField extends RowsField {
+  type: 'blocks'
+  blocks: SchemaBlock[]
+}
+
+export type SchemaField =
+  | ScalarField
+  | NumberField
+  | DateField
+  | ChoiceField
+  | RelationField
+  | GroupField
+  | ArrayField
+  | BlocksField
+
+export type SchemaFieldType = SchemaField['type']
+
+/**
+ * The field kinds that can have one of the given types: `FieldOf<'select'>` is
+ * `ChoiceField`, `FieldOf<'text' | 'email'>` is `ScalarField`. (A plain
+ * `Extract` would give `never`, since a kind's `type` is itself a union.)
+ */
+export type FieldOf<T extends SchemaFieldType> = SchemaField extends infer F
+  ? F extends { type: infer U }
+    ? [Extract<U, T>] extends [never]
+      ? never
+      : F
+    : never
+  : never
+
+/** An array or blocks field: one that holds a list of rows. */
+export type ListField = ArrayField | BlocksField
+
+export const isListField = (field: SchemaField): field is ListField =>
+  field.type === 'array' || field.type === 'blocks'
+
 export interface SchemaBlock {
   slug: string
-  labels: { singular: string; plural: string }
+  labels: SchemaLabels
   fields: SchemaField[]
 }
 
 /** The editable shape of one collection or global, as served by the plugin. */
 export interface DocumentSchema {
-  kind: 'collection' | 'global'
+  kind: DocRef['kind']
   slug: string
-  labels: { singular: string; plural: string }
+  labels: SchemaLabels
   /** Top-level field names the editor may change. */
   editable: string[]
   fields: SchemaField[]

package/src/seal.ts

@@ -100,3 +100,34 @@ export async function sha256(input: string): Promise<string> {
   const d = new Uint8Array(await crypto.subtle.digest('SHA-256', enc.encode(input)))
   return Array.from(d, (b) => b.toString(16).padStart(2, '0')).join('')
 }
+
+/**
+ * The sealed `onpage_preview` cookie a share link sets: which page it opens,
+ * until when, and Next's draft secret to inject for that page only. Written by
+ * the plugin, read by the Next proxy.
+ */
+export interface PreviewGrant {
+  /** The page's pathname. */
+  path: string
+  /** The document's ref key. */
+  ref: string
+  /** Expiry, seconds since the epoch. */
+  exp: number
+  /** Next's draft-mode secret. */
+  draft: string
+}
+
+/** A well-formed grant that hasn't expired. Anything else, including a missing `exp`, is refused. */
+export function isLivePreviewGrant(value: unknown, now = Date.now()): value is PreviewGrant {
+  if (!value || typeof value !== 'object') return false
+  const g = value as Partial<Record<keyof PreviewGrant, unknown>>
+  return (
+    typeof g.path === 'string' &&
+    typeof g.ref === 'string' &&
+    typeof g.draft === 'string' &&
+    !!g.draft &&
+    typeof g.exp === 'number' &&
+    Number.isFinite(g.exp) &&
+    g.exp * 1000 > now
+  )
+}