@payload-onpage/react 0.2.1 → 0.3.0

package/src/registry.ts

@@ -7,24 +7,37 @@
  * No match: the field isn't edited in place (it may still be in the row's
  * settings panel).
  */
-import type { SchemaField, TargetKind } from '@payload-onpage/core'
-import type { EditorRegistry } from './types.ts'
+import type { FieldOf, SchemaField, SchemaFieldType, TargetKind } from '@payload-onpage/core'
+import type { EditorRegistry, FieldEditorDef, FieldEditorProps } from './types.ts'
+import type { ComponentType } from 'react'
 
 const KIND_EDITOR: Partial<Record<TargetKind, string>> = { richtext: 'richText', media: 'upload' }
-const TEXTUAL = new Set(['text', 'textarea', 'email'])
+/** Field types a "text" marker or annotation keeps as their own editor (email stays email). */
+const TEXT_TYPES: ReadonlySet<SchemaFieldType> = new Set(['text', 'textarea', 'email'])
+
+/** Can this editor take this field? Its declared kinds, and never a list of values in place. */
+export function canEdit(
+  def: FieldEditorDef | undefined,
+  field: SchemaField,
+): def is FieldEditorDef {
+  if (!def) return false
+  if (def.accepts && !def.accepts.includes(field.type)) return false
+  return !(def.mode === 'inline' && 'hasMany' in field && field.hasMany)
+}
 
 export function resolveEditor(
   editors: EditorRegistry,
   field: SchemaField,
   kind?: TargetKind,
 ): string | null {
-  if (field.editor && editors[field.editor]) return field.editor
-  // A marker/annotation saying "text" keeps the field's own textual type (email stays email).
-  if ((kind === 'text' || kind === 'textarea') && TEXTUAL.has(field.type) && editors[field.type])
+  const ok = (id: string | undefined): id is string => !!id && canEdit(editors[id], field)
+  if (ok(field.editor)) return field.editor
+  if ((kind === 'text' || kind === 'textarea') && TEXT_TYPES.has(field.type) && ok(field.type))
     return field.type
   const byKind = kind ? KIND_EDITOR[kind] : undefined
-  if (byKind && editors[byKind] && (byKind !== 'upload' || field.type === 'upload')) return byKind
-  return editors[field.type] ? field.type : null
+  // A "media" marker means the image picker only for upload fields (an <img alt> can show a text field).
+  if (ok(byKind) && (byKind !== 'upload' || field.type === 'upload')) return byKind
+  return ok(field.type) ? field.type : null
 }
 
 /** Merge registries left to right; `null` removes a default. */
@@ -41,3 +54,24 @@ export function mergeEditors(
   }
   return out
 }
+
+/**
+ * Define a field editor typed by the field kinds it accepts:
+ *
+ *   defineEditor({
+ *     mode: 'popover',
+ *     accepts: ['number'],
+ *     normalize: (raw) => (typeof raw === 'number' ? raw : null),
+ *     component: ({ field, value }) => … // field: NumberField, value: number | null
+ *   })
+ */
+export function defineEditor<T extends SchemaFieldType, V = unknown>(def: {
+  mode: FieldEditorDef['mode']
+  accepts: readonly T[]
+  normalize?: (raw: unknown, field: FieldOf<T>) => V
+  component: ComponentType<FieldEditorProps<FieldOf<T>, V>>
+}): FieldEditorDef {
+  // Widened once, here: resolveEditor only hands it fields whose type is in `accepts`,
+  // and FieldHost runs `normalize` before rendering.
+  return def as unknown as FieldEditorDef
+}

package/src/rowOps.ts

@@ -0,0 +1,64 @@
+/**
+ * Row operations on array and blocks fields, with one set of rules (bounds,
+ * `minRows`, `maxRows`) for the toolbar, the keyboard shortcuts, the block
+ * picker and "+ Add". Each returns where the selection should go, or null when
+ * the operation isn't allowed (nothing changes).
+ */
+import {
+  cloneRow,
+  insertItem,
+  moveItem,
+  removeItem,
+  updateArray,
+  type EditorSession,
+  type RowInfo,
+  type RefKey,
+} from '@payload-onpage/core'
+import type { Selection } from './types.ts'
+
+const rowAt = (key: RefKey, listPath: string, index: number): Selection => ({
+  key,
+  path: `${listPath}.${index}`,
+})
+
+/** Insert a row into the list at `listPath`; returns the new row's selection. */
+export function insertRow(
+  session: EditorSession,
+  key: RefKey,
+  listPath: string,
+  index: number,
+  row: unknown,
+): Selection {
+  session.apply(key, (d) => updateArray(d, listPath, (a) => insertItem(a, index, row)))
+  return rowAt(key, listPath, index)
+}
+
+export function rowOps(session: EditorSession, key: RefKey, info: RowInfo) {
+  const { listPath, index, length, rowFields, listField } = info
+  const apply = (fn: (rows: unknown[]) => unknown[]) =>
+    session.apply(key, (d) => updateArray(d, listPath, fn))
+  const canMove = (dir: -1 | 1) => index + dir >= 0 && index + dir < length
+  const canDuplicate = listField.maxRows === undefined || length < listField.maxRows
+  const canRemove = length > (listField.minRows ?? 0)
+  return {
+    canMove,
+    canDuplicate,
+    canRemove,
+    move(dir: -1 | 1): Selection | null {
+      if (!canMove(dir)) return null
+      apply((a) => moveItem(a, index, index + dir))
+      return rowAt(key, listPath, index + dir)
+    },
+    duplicate(): Selection | null {
+      if (!canDuplicate) return null
+      apply((a) => insertItem(a, index + 1, cloneRow(a[index], rowFields)))
+      return rowAt(key, listPath, index + 1)
+    },
+    /** Removes the row; true when it did. */
+    remove(): boolean {
+      if (!canRemove) return false
+      apply((a) => removeItem(a, index))
+      return true
+    },
+  }
+}

package/src/sanitize.ts

@@ -50,3 +50,9 @@ export function sanitizeHtml(html: string): string {
   walk(tpl.content)
   return tpl.innerHTML
 }
+
+/** Text made safe to put in HTML. */
+export const escapeHtml = (s: string): string =>
+  s.replace(/[&<>"]/g, (c) => ESCAPES[c as keyof typeof ESCAPES])
+
+const ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' } as const

package/src/settings.ts

@@ -0,0 +1,49 @@
+/**
+ * Which fields of a row appear in its settings panel: values that aren't edited
+ * on the page itself (layout selects, toggles, numbers, links, images that
+ * aren't shown…). Fields shown on the page are edited there instead.
+ */
+import type { SchemaField, SchemaFieldType, RefKey } from '@payload-onpage/core'
+import type { TargetIndex } from './types.ts'
+
+/** Row bookkeeping, never a setting. */
+const SKIP = new Set(['id', 'blockType', 'blockName'])
+
+/** Types shown in the panel when the page doesn't show them (choices and toggles always are). */
+const PANEL_FIELD_TYPES: ReadonlySet<SchemaFieldType> = new Set([
+  'text',
+  'textarea',
+  'email',
+  'number',
+  'date',
+  'relationship',
+  'upload',
+])
+
+export function settable(
+  field: SchemaField,
+  path: string,
+  key: RefKey,
+  targets: TargetIndex,
+): boolean {
+  if (SKIP.has(field.name)) return false
+  const full = `${path}.${field.name}`
+  switch (field.type) {
+    case 'select':
+    case 'radio':
+    case 'checkbox':
+      return true
+    case 'group':
+      return field.fields.some((f) => settable(f, full, key, targets))
+    default:
+      // Shown on the page? Edit it there.
+      return PANEL_FIELD_TYPES.has(field.type) && !targets.find(key, full)
+  }
+}
+
+export const hasSettings = (
+  fields: SchemaField[],
+  path: string,
+  key: RefKey,
+  targets: TargetIndex,
+): boolean => fields.some((f) => settable(f, path, key, targets))

package/src/styles.ts

@@ -2,6 +2,7 @@
  * The editor's own styles, injected once. Everything is prefixed `po-` and set
  * explicitly, so the host site's CSS (and its absence) doesn't matter.
  */
+import { DOM_ATTR } from './dom.ts'
 export const PO_Z = 2147483000
 
 export const PO_CSS = `
@@ -116,7 +117,7 @@ export function injectStyles() {
   if (injected || typeof document === 'undefined') return
   injected = true
   const el = document.createElement('style')
-  el.setAttribute('data-onpage-styles', '')
+  el.setAttribute(DOM_ATTR.styles, '')
   el.textContent = PO_CSS
   document.head.appendChild(el)
 }

package/src/targets.ts

@@ -42,7 +42,7 @@ export function buildIndex(all: Target[]): TargetIndex {
 export function targetsAt(
   index: TargetIndex,
   el: Element | null,
-): { field?: Target; rows: Target[] } {
+): { field?: Target | undefined; rows: Target[] } {
   let field: Target | undefined
   const rows: Target[] = []
   for (let node = el; node; node = node.parentElement) {

package/src/types.ts

@@ -6,41 +6,47 @@ import type {
   MediaLibrary,
   Renderer,
   SchemaField,
+  SchemaFieldType,
   SessionSnapshot,
   Target,
   TargetKind,
+  RefKey,
 } from '@payload-onpage/core'
-import type { MessageKey, Translate } from './messages.ts'
+import type { Translate } from './messages.ts'
 
 export interface EditingState {
   /** refKey of the document */
-  key: string
+  key: RefKey
   path: string
   /** Editor id from the registry ("text", "richText", …). */
   editor: string
-  point?: { x: number; y: number }
+  point?: { x: number; y: number } | undefined
   /** The element that was clicked (several elements may show one field). */
-  el?: Element
+  el?: Element | undefined
 }
 
+/** Which panel is open. */
 export type Panel =
-  | { kind: 'settings'; key: string; path: string; title: string }
-  | { kind: 'blocks'; key: string; listPath: string; index: number }
+  | { kind: 'settings'; key: RefKey; path: string; title: string }
+  | { kind: 'blocks'; key: RefKey; listPath: string; index: number }
   | null
 
 export interface Selection {
-  key: string
+  key: RefKey
   path: string
 }
 
-/** Props every field editor receives. */
-export interface FieldEditorProps {
-  docKey: string
+/**
+ * Props a field editor receives. `F` is the field kind it edits (e.g.
+ * `NumberField`, with `min`/`max`) and `V` its value after `normalize`.
+ */
+export interface FieldEditorProps<F extends SchemaField = SchemaField, V = unknown> {
+  docKey: RefKey
   path: string
-  field: SchemaField
+  field: F
   /** The element showing the field (re-resolved after each refresh). */
   element: () => Element | null
-  value: unknown
+  value: V
   /** Commit a value (one undo step, autosaved). */
   commit: (value: unknown) => void
   /** Live preview while editing (no history entry, not saved). */
@@ -48,23 +54,35 @@ export interface FieldEditorProps {
   /** Close the editor (after commit, or to cancel: transient previews are reverted). */
   close: () => void
   /** Leave a stand-in showing the new content until the page re-renders (refresh mode). */
-  ghost: (g: { html: string; className?: string; style?: Partial<CSSStyleDeclaration> }) => void
+  ghost: (g: GhostInput) => void
   /** True when the page renders this document from editor state (instant); false = server refresh. */
   live: boolean
-  point?: { x: number; y: number }
+  point?: { x: number; y: number } | undefined
   /** UI strings. */
   t: Translate
 }
 
+/** What an editor leaves on the page until it re-renders. */
+export interface GhostInput {
+  html: string
+  className?: string | undefined
+  style?: Partial<CSSStyleDeclaration> | undefined
+}
+
 /**
  * A field editor (the FieldEditor port). `inline` editors replace the element
  * in place (text, rich text); `popover` editors open beside it or as a dialog
  * (select, date, relationship, image…). Register your own by id and refer to it
  * from a field with `admin: { custom: { onpage: { editor: 'my-id' } } }`, or by
- * field type ("json", "code"…) to replace or add a default.
+ * field type ("json", "code"…) to replace or add a default. Build one with
+ * `defineEditor()` so its props are typed by the field kinds it accepts.
  */
 export interface FieldEditorDef {
   mode: 'inline' | 'popover'
+  /** Field types it can edit. The registry never hands it any other kind. Default: any. */
+  accepts?: readonly SchemaFieldType[]
+  /** The raw stored value → the editor's value. Default: passed through. */
+  normalize?: (raw: unknown, field: SchemaField) => unknown
   component: ComponentType<FieldEditorProps>
 }
 
@@ -81,52 +99,67 @@ export interface TargetIndex {
   all: Target[]
   /** Targets whose element is exactly `el`. */
   at: (el: Element) => Target[]
-  find: (key: string, path: string, kinds?: TargetKind[]) => Target | undefined
+  find: (key: RefKey, path: string, kinds?: TargetKind[]) => Target | undefined
 }
 
-/** What extensions and field editors can use from the editor (`useOnPage()`). */
-export interface OnPageContextValue {
+/** A short message shown in the dock. */
+export interface Flash {
+  text: string
+  bad?: boolean | undefined
+}
+
+/**
+ * The editor's stable API: the session, configuration and actions. It changes
+ * only when the editor is reconfigured, so components that only act (toolbars,
+ * custom UI, client-mode documents) don't re-render on every keystroke.
+ */
+export interface OnPageApi {
   session: EditorSession
-  snap: SessionSnapshot
   renderer: Renderer
-  media?: MediaLibrary
+  media?: MediaLibrary | undefined
   editors: EditorRegistry
-  targets: TargetIndex
   links: Links
   t: Translate
-  panel: Panel
   setPanel: (p: Panel) => void
-  editing: EditingState | null
   setEditing: (e: EditingState | null) => void
-  selected: Selection | null
   setSelected: (s: Selection | null) => void
-  /** Documents shown on the current page (the session may hold others from earlier pages). */
-  docKeys: string[]
   /** Is this document rendered from session state (client mode)? */
-  isLive: (key: string) => boolean
+  isLive: (key: RefKey) => boolean
   /** Client-mode documents register here (they don't need a server refresh). */
-  registerClientDoc: (key: string) => () => void
-  /** The page is re-rendering after a save (refresh mode). */
-  rendering: boolean
+  registerClientDoc: (key: RefKey) => () => void
   /** Open the right editor for a field (registry resolution); false if none applies. */
   edit: (
-    key: string,
+    key: RefKey,
     path: string,
-    opts?: { point?: { x: number; y: number }; kind?: TargetKind; anchor?: Element },
+    opts?: {
+      point?: { x: number; y: number } | undefined
+      kind?: TargetKind | undefined
+      anchor?: Element | undefined
+    },
   ) => boolean
   /** Re-render documents after an operation outside autosave (publish, reload). */
   rerender: (refs: DocRef[]) => Promise<void>
-  /** Show a short message in the dock. */
-  notify: (
-    key: MessageKey | (string & {}),
-    vars?: Record<string, string | number>,
-    bad?: boolean,
-  ) => void
-  addGhost: (g: {
-    key: string
-    path: string
-    html: string
-    className?: string
-    style?: Partial<CSSStyleDeclaration>
-  }) => void
+  /** Show a short message in the dock: translated text (`notify(t('notify.published'))`), or an error's text. */
+  notify: (text: string, bad?: boolean) => void
+  addGhost: (g: GhostInput & { key: RefKey; path: string }) => void
+}
+
+/** What changes as people edit: the documents, what's on the page and what's open. */
+export interface OnPageState {
+  snap: SessionSnapshot
+  targets: TargetIndex
+  panel: Panel
+  editing: EditingState | null
+  selected: Selection | null
+  /** Documents shown on the current page (the session may hold others from earlier pages). */
+  docKeys: RefKey[]
+  /** The page is re-rendering after a save (refresh mode). */
+  rendering: boolean
+  /** The dock's current message. */
+  flash: Flash | null
 }
+
+/** Everything inside the editor (`useOnPage()`): its API and its state. */
+export type OnPageContextValue = OnPageApi & OnPageState
+
+export type PanelKind = NonNullable<Panel>['kind']

package/src/ui/BlockPicker.tsx

@@ -1,6 +1,7 @@
 'use client'
 
-import { fieldAtPath, insertItem, newBlockRow, updateArray } from '@payload-onpage/core'
+import { fieldAtPath, isReady, newBlockRow } from '@payload-onpage/core'
+import { insertRow } from '../rowOps.ts'
 import { useOnPage } from '../context.tsx'
 import { Dialog } from './Dialog.tsx'
 
@@ -9,19 +10,17 @@ export function BlockPicker() {
   const { panel, setPanel, snap, session, setSelected, t } = useOnPage()
   if (panel?.kind !== 'blocks') return null
   const state = snap.docs[panel.key]
-  if (!state?.schema || !state.doc) return null
+  if (!isReady(state)) return null
   const { key, listPath, index } = panel
   const field = fieldAtPath(state.schema.fields, state.doc, listPath)?.field
-  const blocks = field?.type === 'blocks' ? (field.blocks ?? []) : []
+  const blocks = field?.type === 'blocks' ? field.blocks : []
 
   const choose = (slug: string) => {
     const block = blocks.find((b) => b.slug === slug)
     if (!block) return
-    session.apply(key, (d) =>
-      updateArray(d, listPath, (a) => insertItem(a, index, newBlockRow(block))),
-    )
+    const next = insertRow(session, key, listPath, index, newBlockRow(block))
     setPanel(null)
-    setSelected({ key, path: `${listPath}.${index}` })
+    setSelected(next)
   }
 
   return (

package/src/ui/Dialog.tsx

@@ -5,6 +5,7 @@
  * close, Tab stays inside (modal), Escape closes. `variant="popover"` is
  * anchored next to an element and closes on an outside click.
  */
+import { useEvent } from '../useEvent.ts'
 import { useEffect, useId, useRef, useState, type CSSProperties, type ReactNode } from 'react'
 import { focusableIn, popoverPosition } from '../dom.ts'
 import { useLayoutTick } from '../layout.ts'
@@ -62,18 +63,21 @@ export function Dialog({
     return () => ro.disconnect()
   }, [variant])
 
+  // Stable, so the listeners below aren't re-bound on every render (callers pass inline
+  // closures); a re-bind would also re-open the deferral gap where an outside click is lost.
+  const close = useEvent(onClose)
   useEffect(() => {
     const onKey = (e: KeyboardEvent) => {
       if (e.key === 'Escape') {
         e.stopPropagation()
-        onClose()
+        close()
         return
       }
       if (e.key !== 'Tab' || variant !== 'modal' || !box.current) return
       const items = focusableIn(box.current)
-      if (!items.length) return
       const first = items[0]
-      const last = items[items.length - 1]
+      const last = items.at(-1)
+      if (!first || !last) return
       if (e.shiftKey && document.activeElement === first) {
         e.preventDefault()
         last.focus()
@@ -83,7 +87,7 @@ export function Dialog({
       }
     }
     const onDown = (e: PointerEvent) => {
-      if (variant === 'popover' && box.current && !box.current.contains(e.target as Node)) onClose()
+      if (variant === 'popover' && box.current && !box.current.contains(e.target as Node)) close()
     }
     document.addEventListener('keydown', onKey, true)
     // Deferred, so the click that opened a popover doesn't close it.
@@ -93,7 +97,7 @@ export function Dialog({
       document.removeEventListener('keydown', onKey, true)
       document.removeEventListener('pointerdown', onDown, true)
     }
-  }, [onClose, variant])
+  }, [close, variant])
 
   const header = (
     <header className="po-dialog-head">