@payload-onpage/core 0.2.0 → 0.3.0

package/src/encode.ts

@@ -9,10 +9,12 @@
  * maps an image). Never tagged: selects, numbers, dates, relationships, JSON,
  * code, and any field whose name suggests machine use (url, slug, email…).
  */
+import type { RefKey } from './docref.ts'
 import { stegaEncode, type Marker } from './stega.ts'
 import type { SchemaField } from './schema.ts'
-import { blockFor } from './fields.ts'
+import { mapFields, type FieldVisitor } from './fields.ts'
 import { mapLexical } from './lexical.ts'
+import { assertNever } from './util.ts'
 
 /** Name segments that mark a field as holding a machine value (never marked). */
 const MACHINE_WORDS = new Set([
@@ -49,11 +51,11 @@ export function isMachineFieldName(name: string): boolean {
 /** Field editors that edit text: a field using any other editor (color, …) holds a machine value and is never marked. */
 const TEXT_EDITORS = new Set(['text', 'textarea', 'email', 'richText'])
 
-export type EncodeFilter = (args: { field: SchemaField; path: string; ref: string }) => boolean
+export type EncodeFilter = (args: { field: SchemaField; path: string; ref: RefKey }) => boolean
 
 interface Ctx {
-  ref: string
-  filter?: EncodeFilter
+  ref: RefKey
+  filter?: EncodeFilter | undefined
 }
 
 const allowed = (field: SchemaField, path: string, ctx: Ctx) =>
@@ -72,62 +74,52 @@ function encodeRichText(value: unknown, ctx: Ctx, path: string): unknown {
   )
 }
 
-function encodeValue(value: unknown, field: SchemaField, path: string, ctx: Ctx): unknown {
-  if (value == null) return value
-  switch (field.type) {
-    case 'text':
-    case 'textarea':
-      if (typeof value === 'string' && value && allowed(field, path, ctx))
-        return mark(value, ctx, path, field.type === 'textarea' ? 'textarea' : 'text')
-      return value
-    case 'richText':
-      return allowed(field, path, ctx) ? encodeRichText(value, ctx, path) : value
-    case 'upload':
-      if (!field.hasMany && value && typeof value === 'object' && !Array.isArray(value)) {
-        const media = value as Record<string, unknown>
-        return {
-          ...media,
-          alt: mark(typeof media.alt === 'string' ? media.alt : '', ctx, path, 'media'),
+/** What each leaf field kind gets: text and rich text are marked, a populated upload's `alt` carries its path. */
+const encoding = (ctx: Ctx): FieldVisitor => ({
+  leaf: (value, field, path) => {
+    switch (field.type) {
+      case 'text':
+      case 'textarea':
+        return typeof value === 'string' && value && allowed(field, path, ctx)
+          ? mark(value, ctx, path, field.type)
+          : value
+      case 'richText':
+        return allowed(field, path, ctx) ? encodeRichText(value, ctx, path) : value
+      case 'upload':
+        if (!field.hasMany && value && typeof value === 'object' && !Array.isArray(value)) {
+          const media = value as Record<string, unknown>
+          return {
+            ...media,
+            alt: mark(typeof media.alt === 'string' ? media.alt : '', ctx, path, 'media'),
+          }
         }
-      }
-      return value
-    case 'group':
-      return encodeFields(value, field.fields ?? [], path, ctx)
-    case 'array':
-      return Array.isArray(value)
-        ? (value as unknown[]).map((row: unknown, i: number) =>
-            encodeFields(row, field.fields ?? [], `${path}.${i}`, ctx),
-          )
-        : value
-    case 'blocks':
-      return Array.isArray(value)
-        ? (value as unknown[]).map((row: unknown, i: number) => {
-            const block = blockFor(field, row)
-            return block ? encodeFields(row, block.fields, `${path}.${i}`, ctx) : row
-          })
-        : value
-    default:
-      return value
-  }
-}
-
-function encodeFields(data: unknown, fields: SchemaField[], prefix: string, ctx: Ctx): unknown {
-  if (!data || typeof data !== 'object' || Array.isArray(data)) return data
-  const out: Record<string, unknown> = { ...(data as Record<string, unknown>) }
-  for (const f of fields) {
-    if (!(f.name in out)) continue
-    out[f.name] = encodeValue(out[f.name], f, prefix ? `${prefix}.${f.name}` : f.name, ctx)
-  }
-  return out
-}
+        return value
+      // Machine values: never marked.
+      case 'email':
+      case 'code':
+      case 'json':
+      case 'checkbox':
+      case 'point':
+      case 'number':
+      case 'date':
+      case 'select':
+      case 'radio':
+      case 'relationship':
+        return value
+      default:
+        return assertNever(field, 'field type')
+    }
+  },
+})
 
 /** Return a copy of `doc` with markers on the given (editable) top-level fields. */
 export function encodeDocument<T extends Record<string, unknown>>(
   doc: T,
   fields: SchemaField[],
-  ref: string,
-  opts: { only?: string[]; filter?: EncodeFilter } = {},
+  ref: RefKey,
+  opts: { only?: string[] | undefined; filter?: EncodeFilter | undefined } = {},
 ): T {
-  const scope = opts.only ? fields.filter((f) => opts.only!.includes(f.name)) : fields
-  return encodeFields(doc, scope, '', { ref, filter: opts.filter }) as T
+  const { only } = opts
+  const scope = only ? fields.filter((f) => only.includes(f.name)) : fields
+  return mapFields(doc, scope, encoding({ ref, filter: opts.filter })) as T
 }

package/src/fields.ts

@@ -3,21 +3,102 @@
  * new blocks/rows from defaults, clone rows with fresh ids, and normalize data
  * for saving (populated relations back to ids).
  */
-import { getAt, newRowId, parsePath, type PathSegment } from './path.ts'
+import { getAt, newRowId, parsePath, splitItemPath, type PathSegment } from './path.ts'
 import { mapLexical } from './lexical.ts'
-import type { DocumentSchema, SchemaBlock, SchemaField } from './schema.ts'
+import type {
+  ArrayField,
+  BlocksField,
+  DocumentSchema,
+  GroupField,
+  ListField,
+  RelationField,
+  SchemaBlock,
+  SchemaField,
+} from './schema.ts'
+import { isListField } from './schema.ts'
+import { assertNever } from './util.ts'
 
 export interface FieldAtPath {
   field: SchemaField
   /** The block whose fields contain this field, when inside a blocks row. */
-  block?: SchemaBlock
+  block?: SchemaBlock | undefined
   /** Path of the nearest blocks row ("sections.3"), when inside one. */
-  blockPath?: string
+  blockPath?: string | undefined
 }
 
+type Data = Record<string, unknown>
+
+const isData = (value: unknown): value is Data =>
+  !!value && typeof value === 'object' && !Array.isArray(value)
+
 /** The block a blocks-field row uses (by its `blockType`). */
-export const blockFor = (field: SchemaField, row: unknown): SchemaBlock | undefined =>
-  field.blocks?.find((b) => b.slug === (row as { blockType?: unknown } | null)?.blockType)
+export const blockFor = (field: BlocksField, row: unknown): SchemaBlock | undefined =>
+  isData(row) ? field.blocks.find((b) => b.slug === row.blockType) : undefined
+
+/** The fields of one row of a list field: the block's fields, or the array's. */
+export const rowFieldsOf = (field: ListField, row: unknown): SchemaField[] | undefined =>
+  field.type === 'blocks' ? blockFor(field, row)?.fields : field.fields
+
+/** A field that holds other fields' data. */
+type Container = GroupField | ArrayField | BlocksField
+/** Any other field: its value is handled as one unit. */
+export type LeafField = Exclude<SchemaField, Container>
+
+export interface FieldVisitor {
+  /** Every field that isn't a group, array or blocks field. Return the value unchanged to keep it. */
+  leaf: (value: unknown, field: LeafField, path: string) => unknown
+  /** Each array/blocks row (a copy), before its fields are visited: e.g. give it a new id. */
+  row?: (row: Data, path: string) => Data
+  /** A blocks row with an unknown `blockType`. Default: kept as is. */
+  unknownBlock?: (row: unknown) => unknown
+}
+
+/**
+ * Rebuild document data field by field. Groups, array rows and block rows are
+ * walked here, once, for every schema-aware transform (cloning, normalizing for
+ * a save, encoding markers); `visit` only says what to do with leaf fields.
+ * Values of fields missing from `data` stay missing; untouched values are shared.
+ */
+export function mapFields(
+  data: unknown,
+  fields: SchemaField[],
+  visit: FieldVisitor,
+  prefix = '',
+): unknown {
+  if (!isData(data)) return data
+  const out: Data = { ...data }
+  for (const f of fields)
+    if (f.name in out)
+      out[f.name] = mapField(out[f.name], f, visit, prefix ? `${prefix}.${f.name}` : f.name)
+  return out
+}
+
+/** One field's value (see `mapFields`). */
+export function mapField(
+  value: unknown,
+  field: SchemaField,
+  visit: FieldVisitor,
+  path: string,
+): unknown {
+  if (value == null) return value
+  switch (field.type) {
+    case 'group':
+      return mapFields(value, field.fields, visit, path)
+    case 'array':
+    case 'blocks':
+      return Array.isArray(value)
+        ? value.map((row: unknown, i) => {
+            const fields = rowFieldsOf(field, row)
+            if (!fields) return visit.unknownBlock ? visit.unknownBlock(row) : row
+            const rowPath = `${path}.${i}`
+            const base = isData(row) && visit.row ? visit.row({ ...row }, rowPath) : row
+            return mapFields(base, fields, visit, rowPath)
+          })
+        : value
+    default:
+      return visit.leaf(value, field, path)
+  }
+}
 
 /** May the editor change this path? (Its top-level field must be editable.) */
 export const isEditablePath = (schema: DocumentSchema, path: string): boolean =>
@@ -30,7 +111,7 @@ export interface RowInfo {
   listPath: string
   index: number
   length: number
-  listField: SchemaField
+  listField: ListField
   /** Fields of this row: the block's fields, or the array's. */
   rowFields: SchemaField[]
   /** Singular label of one row ("Hero", "Feature"). */
@@ -40,15 +121,13 @@ export interface RowInfo {
 
 /** Everything the editor needs about one row of an array or blocks field, or null if `path` isn't an editable row. */
 export function resolveRow(schema: DocumentSchema, doc: unknown, path: string): RowInfo | null {
-  const segs = path.split('.')
-  const last = segs[segs.length - 1]
-  if (!last || !/^\d+$/.test(last) || !isEditablePath(schema, path)) return null
-  const listPath = segs.slice(0, -1).join('.')
-  const index = Number(last)
+  const split = splitItemPath(path)
+  if (!split || !isEditablePath(schema, path)) return null
+  const [listPath, index] = split
   const listField = fieldAtPath(schema.fields, doc, listPath)?.field
-  if (!listField || (listField.type !== 'array' && listField.type !== 'blocks')) return null
-  const rows = getAt<unknown[]>(doc, listPath) ?? []
-  if (index >= rows.length) return null
+  if (!listField || !isListField(listField)) return null
+  const rows = getAt(doc, listPath)
+  if (!Array.isArray(rows) || index >= rows.length) return null
   const isBlock = listField.type === 'blocks'
   const block = isBlock ? blockFor(listField, rows[index]) : undefined
   return {
@@ -57,10 +136,10 @@ export function resolveRow(schema: DocumentSchema, doc: unknown, path: string):
     index,
     length: rows.length,
     listField,
-    rowFields: isBlock ? (block?.fields ?? []) : (listField.fields ?? []),
-    label: isBlock
-      ? (block?.labels.singular ?? 'Section')
-      : (listField.labels?.singular ?? listField.label),
+    rowFields: rowFieldsOf(listField, rows[index]) ?? [],
+    label:
+      block?.labels.singular ??
+      (isBlock ? 'Section' : (listField.labels?.singular ?? listField.label)),
     isBlock,
   }
 }
@@ -80,85 +159,63 @@ export function fieldAtPath(
   let current: SchemaField | undefined
   let block: SchemaBlock | undefined
   let blockPath: string | undefined
-  for (let i = 0; i < segs.length; i++) {
-    const seg = segs[i]
+  for (const [i, seg] of segs.entries()) {
     if (typeof seg === 'number') {
-      if (!current) return null
+      if (!current || !isListField(current)) return null
       if (current.type === 'blocks') {
         const rowPath = segs.slice(0, i + 1)
         block = blockFor(current, getAt(doc, rowPath))
         if (!block) return null
         blockPath = rowPath.join('.')
         level = block.fields
-      } else if (current.type === 'array') {
-        level = current.fields ?? []
       } else {
-        return null
+        level = current.fields
       }
       continue
     }
     current = level.find((f) => f.name === seg)
     if (!current) return null
-    if (current.type === 'group') level = current.fields ?? []
+    if (current.type === 'group') level = current.fields
   }
   return current ? { field: current, block, blockPath } : null
 }
 
 /** Defaults for a set of fields: static `defaultValue`s, nested groups, `minRows` rows. */
-export function defaultsFor(fields: SchemaField[]): Record<string, unknown> {
-  const out: Record<string, unknown> = {}
+export function defaultsFor(fields: SchemaField[]): Data {
+  const out: Data = {}
   for (const f of fields) {
-    if (f.defaultValue !== undefined) {
-      out[f.name] = structuredClone(f.defaultValue)
-    } else if (f.type === 'group') {
-      out[f.name] = defaultsFor(f.fields ?? [])
-    } else if (f.type === 'array') {
+    if (f.defaultValue !== undefined) out[f.name] = structuredClone(f.defaultValue)
+    else if (f.type === 'group') out[f.name] = defaultsFor(f.fields)
+    else if (f.type === 'array')
       out[f.name] = Array.from({ length: f.minRows ?? 0 }, () => newArrayRow(f))
-    } else if (f.type === 'blocks') {
-      out[f.name] = []
-    } else if (f.required && (f.type === 'text' || f.type === 'textarea')) {
-      out[f.name] = f.label
-    }
+    else if (f.type === 'blocks') out[f.name] = []
+    else if (f.required && (f.type === 'text' || f.type === 'textarea')) out[f.name] = f.label
   }
   return out
 }
 
-export function newArrayRow(arrayField: SchemaField): Record<string, unknown> {
-  return { id: newRowId(), ...defaultsFor(arrayField.fields ?? []) }
+export function newArrayRow(arrayField: ArrayField): Data {
+  return { id: newRowId(), ...defaultsFor(arrayField.fields) }
 }
 
-export function newBlockRow(block: SchemaBlock): Record<string, unknown> {
+export function newBlockRow(block: SchemaBlock): Data {
   return { id: newRowId(), blockType: block.slug, ...defaultsFor(block.fields) }
 }
 
+/** Cloning: every row gets a new id; related documents' ids are kept; other objects are deep-copied. */
+const cloning: FieldVisitor = {
+  leaf: (value) => (typeof value === 'object' ? structuredClone(value) : value),
+  row: (row) => ({ ...row, id: newRowId() }),
+  unknownBlock: (row) => structuredClone(row),
+}
+
 /**
  * Deep-clone a row (array item or block) giving it, and every nested row, a new
  * id. Ids of related documents (uploads, relationships) are left alone, so a
  * duplicated card still points at the same image.
  */
 export function cloneRow(row: unknown, rowFields: SchemaField[]): unknown {
-  if (!row || typeof row !== 'object') return row
-  const copy: Record<string, unknown> = { ...(row as Record<string, unknown>), id: newRowId() }
-  for (const f of rowFields) copy[f.name] = cloneValue(copy[f.name], f)
-  return copy
-}
-
-function cloneValue(value: unknown, field: SchemaField): unknown {
-  if (value == null) return value
-  if (field.type === 'group') {
-    const out: Record<string, unknown> = { ...(value as Record<string, unknown>) }
-    for (const f of field.fields ?? []) out[f.name] = cloneValue(out[f.name], f)
-    return out
-  }
-  if (field.type === 'array' && Array.isArray(value))
-    return (value as unknown[]).map((r: unknown) => cloneRow(r, field.fields ?? []))
-  if (field.type === 'blocks' && Array.isArray(value)) {
-    return (value as unknown[]).map((r: unknown) => {
-      const block = blockFor(field, r)
-      return block ? cloneRow(r, block.fields) : structuredClone(r)
-    })
-  }
-  return typeof value === 'object' ? structuredClone(value) : value
+  return isData(row) ? mapFields({ ...row, id: newRowId() }, rowFields, cloning) : row
 }
 
 /** The id of a relationship value: a populated doc, `{ relationTo, value }`, or an id. */
@@ -171,6 +228,23 @@ export function relationId(v: unknown): string | number | undefined {
   return o.id as string | number | undefined
 }
 
+/**
+ * A field value as a list: a hasMany value as its items, a single value as a
+ * one-item list, nothing as []. `item` keeps or converts each entry (return
+ * undefined to drop it).
+ */
+export function asList<T = unknown>(
+  value: unknown,
+  many: boolean | undefined,
+  item: (v: unknown) => T | undefined = (v) => v as T,
+): T[] {
+  const raw = many ? (Array.isArray(value) ? value : []) : value == null ? [] : [value]
+  return raw.flatMap((v) => {
+    const out = item(v)
+    return out === undefined ? [] : [out]
+  })
+}
+
 /** A display title for a relationship value (`titleField` when known, else common title fields, else the id). */
 export function relationTitle(v: unknown, titleField?: string): string {
   if (v && typeof v === 'object') {
@@ -185,7 +259,7 @@ export function relationTitle(v: unknown, titleField?: string): string {
 
 const idOf = (v: unknown): unknown => (v && typeof v === 'object' && 'id' in v ? relationId(v) : v)
 
-function normalizeRelation(value: unknown, field: SchemaField): unknown {
+function normalizeRelation(value: unknown, field: RelationField): unknown {
   if (value == null) return value
   const one = (v: unknown) => {
     // Polymorphic: { relationTo, value }
@@ -198,38 +272,39 @@ function normalizeRelation(value: unknown, field: SchemaField): unknown {
   return Array.isArray(value) ? value.map(one) : one(value)
 }
 
+/** Normalizing for a save: populated relations become ids, rich text drops populated docs. */
+const normalizing: FieldVisitor = {
+  leaf: (value, field) => {
+    switch (field.type) {
+      case 'upload':
+      case 'relationship':
+        return normalizeRelation(value, field)
+      case 'richText':
+        return normalizeRichText(value)
+      case 'text':
+      case 'textarea':
+      case 'email':
+      case 'code':
+      case 'json':
+      case 'checkbox':
+      case 'point':
+      case 'number':
+      case 'date':
+      case 'select':
+      case 'radio':
+        return value
+      default:
+        return assertNever(field, 'field type')
+    }
+  },
+}
+
 /**
  * Turn rendered (populated) data back into what Payload expects on write:
  * uploads and relationships become ids, everything else passes through.
  */
 export function normalizeValue(value: unknown, field: SchemaField): unknown {
-  if (value == null) return value
-  switch (field.type) {
-    case 'upload':
-    case 'relationship':
-      return normalizeRelation(value, field)
-    case 'richText':
-      return normalizeRichText(value)
-    case 'group': {
-      const out: Record<string, unknown> = { ...(value as Record<string, unknown>) }
-      for (const f of field.fields ?? [])
-        if (f.name in out) out[f.name] = normalizeValue(out[f.name], f)
-      return out
-    }
-    case 'array':
-      return Array.isArray(value)
-        ? (value as unknown[]).map((row: unknown) => normalizeRow(row, field.fields ?? []))
-        : value
-    case 'blocks':
-      return Array.isArray(value)
-        ? (value as unknown[]).map((row: unknown) => {
-            const block = blockFor(field, row)
-            return block ? normalizeRow(row, block.fields) : row
-          })
-        : value
-    default:
-      return value
-  }
+  return mapField(value, field, normalizing, field.name)
 }
 
 /**
@@ -258,13 +333,6 @@ export function normalizeRichText(value: unknown): unknown {
 const isPopulated = (v: unknown): v is { id: string | number } =>
   !!v && typeof v === 'object' && 'id' in v
 
-function normalizeRow(row: unknown, rowFields: SchemaField[]): unknown {
-  if (!row || typeof row !== 'object') return row
-  const out: Record<string, unknown> = { ...(row as Record<string, unknown>) }
-  for (const f of rowFields) if (f.name in out) out[f.name] = normalizeValue(out[f.name], f)
-  return out
-}
-
 /** Normalize the given top-level keys of a document for a PATCH body. */
 export function buildPatch(
   doc: Record<string, unknown>,

package/src/index.ts

@@ -3,16 +3,129 @@
  * schema, path and field operations, the stega codec, autosave, the editor
  * session, and the port interfaces adapters implement. The default Payload REST
  * adapters are in `@payload-onpage/core/payload`.
+ *
+ * The public API is listed explicitly: anything not exported here is internal
+ * and may change in any release.
  */
-export * from './docref.ts'
-export * from './path.ts'
-export * from './schema.ts'
-export * from './fields.ts'
-export * from './autosave.ts'
-export * from './stega.ts'
-export * from './encode.ts'
-export * from './lexical.ts'
-export * from './ports.ts'
-export * from './session.ts'
-export * from './seal.ts'
-export * from './constants.ts'
+export {
+  isRefKey,
+  parseRefKey,
+  refKey,
+  targetKey,
+  type DocRef,
+  type RefKey,
+  type TargetKey,
+} from './docref.ts'
+export {
+  getAt,
+  insertItem,
+  moveItem,
+  newRowId,
+  parsePath,
+  pathnameOf,
+  removeItem,
+  rowPrefixes,
+  safeLinkUrl,
+  safePath,
+  samePath,
+  setAt,
+  splitItemPath,
+  updateArray,
+  type PathSegment,
+} from './path.ts'
+export {
+  isListField,
+  type ArrayField,
+  type BlocksField,
+  type ChoiceField,
+  type DateField,
+  type DocumentSchema,
+  type FieldOf,
+  type GroupField,
+  type ListField,
+  type NumberField,
+  type RelationField,
+  type ScalarField,
+  type ScalarFieldType,
+  type SchemaBlock,
+  type SchemaField,
+  type SchemaFieldType,
+  type SchemaLabels,
+  type SchemaOption,
+} from './schema.ts'
+export {
+  asList,
+  blockFor,
+  buildPatch,
+  changedKeys,
+  cloneRow,
+  defaultsFor,
+  fieldAtPath,
+  isEditablePath,
+  newArrayRow,
+  newBlockRow,
+  normalizeRichText,
+  normalizeValue,
+  relationId,
+  relationTitle,
+  resolveRow,
+  rowFieldsOf,
+  toText,
+  type FieldAtPath,
+  type RowInfo,
+} from './fields.ts'
+export { AutosaveQueue, type AutosaveOptions, type SaveState, type SaveStatus } from './autosave.ts'
+export {
+  encodeMarker,
+  hasStegaMarker,
+  stegaClean,
+  stegaCleanDeep,
+  stegaDecode,
+  stegaEncode,
+  type Marker,
+  type MarkerKind,
+} from './stega.ts'
+export { encodeDocument, isMachineFieldName, type EncodeFilter } from './encode.ts'
+export {
+  eachLexicalNode,
+  isLexicalState,
+  mapLexical,
+  type LexicalNode,
+  type LexicalState,
+} from './lexical.ts'
+export {
+  isOnPageMode,
+  isTargetKind,
+  type DataSource,
+  type Doc,
+  type Locator,
+  type MediaItem,
+  type MediaLibrary,
+  type OnPageMode,
+  type PreviewLink,
+  type Renderer,
+  type SaveResult,
+  type SearchHit,
+  type SessionAdapter,
+  type Target,
+  type TargetKind,
+} from './ports.ts'
+export {
+  EditorSession,
+  isReady,
+  type DocumentState,
+  type EditorSessionOptions,
+  type PublishResult,
+  type ReadyDocumentState,
+  type SessionSnapshot,
+} from './session.ts'
+export {
+  isLivePreviewGrant,
+  seal,
+  SEAL_PURPOSE,
+  sha256,
+  unseal,
+  type PreviewGrant,
+} from './seal.ts'
+export { CONTEXT_KEY, COOKIE, DEFAULTS, HEADER, ROUTES } from './constants.ts'
+export { assertNever, errorText } from './util.ts'