@payload-onpage/react 0.0.0-stage → 0.1.0

package/src/editor/Ghosts.tsx

@@ -0,0 +1,55 @@
+'use client'
+
+import { useEffect, useRef } from 'react'
+import { useOnPage } from '../context.tsx'
+import { HIDDEN, placeOver } from '../dom.ts'
+import { useLayoutTick } from '../layout.ts'
+import { sanitizeHtml } from '../sanitize.ts'
+import type { Ghost } from './useGhosts.ts'
+
+/** Refresh mode: committed content stays on screen until the server render shows it. */
+export function Ghosts({ ghosts }: { ghosts: Ghost[] }) {
+  return (
+    <>
+      {ghosts.map((g) => (
+        <GhostView key={g.id} ghost={g} />
+      ))}
+    </>
+  )
+}
+
+function GhostView({ ghost }: { ghost: Ghost }) {
+  const { targets, editing } = useOnPage()
+  const box = useRef<HTMLDivElement>(null)
+  const hidden = useRef<Element | null>(null)
+  const tick = useLayoutTick()
+  const reopened = editing?.key === ghost.key && editing.path === ghost.path
+
+  useEffect(() => {
+    const el = targets.find(ghost.key, ghost.path)?.el ?? null
+    if (hidden.current && hidden.current !== el) hidden.current.removeAttribute(HIDDEN)
+    hidden.current = el
+    const b = box.current
+    if (!b) return
+    if (!el || reopened) {
+      b.style.visibility = 'hidden'
+      return
+    }
+    el.setAttribute(HIDDEN, 'true')
+    placeOver(b, el, { minHeight: true })
+    b.style.visibility = 'visible'
+  }, [targets, ghost.key, ghost.path, reopened, tick])
+
+  useEffect(() => () => hidden.current?.removeAttribute(HIDDEN), [])
+
+  return (
+    <div
+      ref={box}
+      className={`po-ghost${ghost.className ? ` ${ghost.className}` : ''}`}
+      style={ghost.style as React.CSSProperties}
+      dangerouslySetInnerHTML={{ __html: sanitizeHtml(ghost.html) }}
+      aria-hidden
+      data-testid="onpage-ghost"
+    />
+  )
+}

package/src/editor/OnPageEditor.tsx

@@ -0,0 +1,315 @@
+'use client'
+
+/**
+ * The on-page editor. Mount it once (the Next adapter's <OnPage /> does) and
+ * it finds editable content through the Locator, opens each document it finds
+ * in an EditorSession, and edits through the field-editor registry. Saves go
+ * through the DataSource; the Renderer shows them (server refresh by default,
+ * instant for documents rendered with <OnPageClient>).
+ */
+import { useEvent } from '../useEvent.ts'
+import {
+  EditorSession,
+  fieldAtPath,
+  isEditablePath,
+  refKey,
+  type DataSource,
+  type DocRef,
+  type Locator,
+  type MediaLibrary,
+  type Renderer,
+  type SessionSnapshot,
+} from '@payload-onpage/core'
+import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from 'react'
+import { createPortal } from 'react-dom'
+import { OnPageContext } from '../context.tsx'
+import { UI } from '../dom.ts'
+import { defaultEditors } from '../editors/index.ts'
+import { hub } from '../hub.ts'
+import { notifyLayout } from '../layout.ts'
+import { annotations, composite, stega } from '../locators.ts'
+import { createTranslate, type Messages } from '../messages.ts'
+import { mergeEditors, resolveEditor } from '../registry.ts'
+import { clientState } from '../renderers.ts'
+import { injectStyles } from '../styles.ts'
+import { useTargets } from '../targets.ts'
+import type {
+  EditingState,
+  EditorRegistry,
+  FieldEditorDef,
+  Links,
+  OnPageContextValue,
+  Panel,
+  Selection,
+} from '../types.ts'
+import { BlockPicker } from '../ui/BlockPicker.tsx'
+import { Dock } from '../ui/Dock.tsx'
+import { Overlay } from '../ui/Overlay.tsx'
+import { SettingsPanel } from '../ui/SettingsPanel.tsx'
+import { FieldHost } from './FieldHost.tsx'
+import { Ghosts } from './Ghosts.tsx'
+import { usePageEvents } from './usePageEvents.ts'
+import { useGhosts } from './useGhosts.ts'
+
+export interface OnPageEditorProps {
+  dataSource: DataSource
+  /** Image search/upload (e.g. `payloadUploads()`). Without it, upload fields can't be changed. */
+  media?: MediaLibrary
+  /** How elements map to fields. Default: composite(annotations(), stega()). */
+  locator?: Locator
+  /** How saved changes reach the page. Default: clientState() (no server refresh). */
+  renderer?: Renderer
+  /** Extra or replacement field editors by id; `null` removes a default. */
+  editors?: Record<string, FieldEditorDef | null>
+  links: Links
+  /** Content locale to edit. */
+  locale?: string
+  /** Autosave debounce, ms. Default: 250 with a refreshing renderer; else the collection's autosave interval, else 800. */
+  autosaveDelay?: number
+  /** Where to look for editable content. Default: document.body. */
+  root?: () => ParentNode | null
+  /** Override any UI string (see `defaultMessages`). */
+  messages?: Messages
+}
+
+const EMPTY_SNAP: SessionSnapshot = { docs: {}, canUndo: false, canRedo: false, busy: false }
+const noopSubscribe = () => () => {}
+
+export function OnPageEditor(props: OnPageEditorProps) {
+  const { dataSource, locale, autosaveDelay, links, media } = props
+  const renderer = useMemo(() => props.renderer ?? clientState(), [props.renderer])
+  const locator = useMemo(() => props.locator ?? composite(annotations(), stega()), [props.locator])
+  const editors: EditorRegistry = useMemo(
+    () => mergeEditors(defaultEditors, props.editors),
+    [props.editors],
+  )
+  const t = useMemo(() => createTranslate(props.messages), [props.messages])
+  const rootProp = props.root
+  const root = useCallback(
+    () => (rootProp ? rootProp() : typeof document === 'undefined' ? null : document.body),
+    [rootProp],
+  )
+
+  const [panel, setPanel] = useState<Panel>(null)
+  const [editing, setEditing] = useState<EditingState | null>(null)
+  const [selected, setSelected] = useState<Selection | null>(null)
+  const [renders, setRenders] = useState(0)
+  const [flash, setFlash] = useState<{ text: string; bad?: boolean } | null>(null)
+  const [clientDocs, setClientDocs] = useState<ReadonlySet<string>>(() => new Set())
+  const [session, setSession] = useState<EditorSession | null>(null)
+  const snap = useSyncExternalStore(
+    session?.subscribe ?? noopSubscribe,
+    session?.getSnapshot ?? (() => EMPTY_SNAP),
+    () => EMPTY_SNAP,
+  )
+  const targets = useTargets(locator, root)
+  const { ghosts, add: addGhostEntry, rendered: ghostsRendered } = useGhosts(session ? snap : null)
+
+  const isLive = useCallback(
+    (key: string) => renderer.live || clientDocs.has(key),
+    [renderer, clientDocs],
+  )
+
+  /** Re-render documents that aren't client-rendered, then retire their ghosts. */
+  const rerender = useCallback(
+    async (refs: DocRef[], seq?: number) => {
+      const stale = refs.filter((r) => !isLive(refKey(r)))
+      if (!stale.length) return
+      setRenders((n) => n + 1)
+      try {
+        await renderer.afterSave({ refs: stale })
+      } catch (e) {
+        console.error('[payload-onpage] render after save failed', e)
+      } finally {
+        setRenders((n) => n - 1)
+        // Give the new DOM a moment to land (and the locator to rescan) before uncovering it.
+        setTimeout(() => {
+          for (const r of stale) ghostsRendered(refKey(r), seq ?? Number.MAX_SAFE_INTEGER)
+        }, 250)
+      }
+    },
+    [isLive, renderer, ghostsRendered],
+  )
+
+  const handleSaved = useEvent((ref: DocRef, seq: number) => void rerender([ref], seq))
+
+  // One session per data source and locale; disposed (after flushing) when they change or on unmount.
+  useEffect(() => {
+    // Refresh mode saves quickly (the page only updates after a save); client mode uses the collection's interval.
+    const delay = autosaveDelay ?? (renderer.live ? undefined : 250)
+    const s = new EditorSession({
+      dataSource,
+      locale,
+      autosaveDelay: delay,
+      onSaved: (ref, seq) => handleSaved(ref, seq),
+    })
+    // The session is an external resource with a lifecycle; it lives in state so StrictMode's
+    // mount/unmount/mount gets a fresh one each time.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setSession(s)
+    return () => {
+      void s.flush().finally(() => s.dispose())
+    }
+  }, [dataSource, locale, autosaveDelay, renderer.live, handleSaved])
+
+  useEffect(() => {
+    if (!flash) return
+    const id = setTimeout(() => setFlash(null), 4000)
+    return () => clearTimeout(id)
+  }, [flash])
+
+  // Documents on this page: everything the locator found, plus client-mode documents.
+  const docKeys = useMemo(() => {
+    const keys = new Set<string>(clientDocs)
+    for (const target of targets.all) keys.add(refKey(target.ref))
+    return [...keys]
+  }, [targets, clientDocs])
+
+  useEffect(() => {
+    if (!session) return
+    const seen = new Set<string>()
+    for (const target of targets.all) {
+      const k = refKey(target.ref)
+      if (seen.has(k)) continue
+      seen.add(k)
+      void session.open(target.ref)
+    }
+  }, [targets, session])
+
+  useEffect(() => notifyLayout(), [snap, targets])
+
+  const notify = useCallback<OnPageContextValue['notify']>(
+    (key, vars, bad) => setFlash({ text: t(key, vars), bad }),
+    [t],
+  )
+
+  const registerClientDoc = useCallback((key: string) => {
+    setClientDocs((s) => new Set(s).add(key))
+    return () =>
+      setClientDocs((s) => {
+        const next = new Set(s)
+        next.delete(key)
+        return next
+      })
+  }, [])
+
+  const addGhost = useCallback<OnPageContextValue['addGhost']>(
+    (g) => addGhostEntry(g, session?.get(g.key)?.save.seq ?? 0),
+    [addGhostEntry, session],
+  )
+
+  const edit = useCallback<OnPageContextValue['edit']>(
+    (key, path, opts = {}) => {
+      const state = session?.get(key)
+      if (!state?.schema || !state.doc) {
+        if (state?.status === 'error')
+          notify('notify.cantEdit', { message: state.error ?? '' }, true)
+        else notify('notify.loading')
+        return true
+      }
+      if (!isEditablePath(state.schema, path)) return false
+      const hit = fieldAtPath(state.schema.fields, state.doc, path)
+      if (!hit) return false
+      const editor = resolveEditor(
+        editors,
+        hit.field,
+        opts.kind === 'field' ? undefined : opts.kind,
+      )
+      if (!editor) return false
+      setEditing({
+        key,
+        path,
+        editor,
+        point: opts.point,
+        el: opts.anchor ?? targets.find(key, path)?.el,
+      })
+      return true
+    },
+    [session, editors, targets, notify],
+  )
+
+  const ctx = useMemo<OnPageContextValue | null>(
+    () =>
+      session && {
+        session,
+        snap,
+        renderer,
+        media,
+        editors,
+        targets,
+        links,
+        t,
+        panel,
+        setPanel,
+        editing,
+        setEditing,
+        selected,
+        setSelected,
+        docKeys,
+        isLive,
+        registerClientDoc,
+        rendering: renders > 0,
+        edit,
+        rerender: (refs) => rerender(refs),
+        notify,
+        addGhost,
+      },
+    [
+      session,
+      snap,
+      renderer,
+      media,
+      editors,
+      targets,
+      links,
+      t,
+      panel,
+      editing,
+      selected,
+      docKeys,
+      isLive,
+      registerClientDoc,
+      renders,
+      edit,
+      rerender,
+      notify,
+      addGhost,
+    ],
+  )
+
+  useEffect(() => {
+    hub.set(ctx)
+  }, [ctx])
+  useEffect(() => () => hub.set(null), [])
+  useEffect(() => injectStyles(), [])
+  usePageEvents(ctx, root)
+
+  const mounted = useSyncExternalStore(
+    noopSubscribe,
+    () => true,
+    () => false,
+  )
+  if (!mounted || !ctx) return null
+
+  return (
+    <OnPageContext.Provider value={ctx}>
+      {createPortal(
+        <div className="po-doc-layer" {...{ [UI]: '' }}>
+          <Ghosts ghosts={ghosts} />
+          <FieldHost mode="inline" />
+        </div>,
+        document.body,
+      )}
+      {createPortal(
+        <div className="po-layer" {...{ [UI]: '' }}>
+          <Overlay />
+          <SettingsPanel />
+          <BlockPicker />
+          <FieldHost mode="popover" />
+          <Dock flash={flash} />
+        </div>,
+        document.body,
+      )}
+    </OnPageContext.Provider>
+  )
+}

package/src/editor/useGhosts.ts

@@ -0,0 +1,64 @@
+'use client'
+
+/**
+ * Ghosts: in refresh mode, committed content stays on screen (over the hidden
+ * original) until the server render that includes it has landed. A ghost
+ * records the document's save sequence when it was made; the render after a
+ * later save retires it. Failed saves and a TTL retire ghosts too.
+ */
+import type { SessionSnapshot } from '@payload-onpage/core'
+import { useCallback, useEffect, useState } from 'react'
+
+export interface Ghost {
+  id: string
+  key: string
+  path: string
+  html: string
+  className?: string
+  style?: Partial<CSSStyleDeclaration>
+  /** Save sequence of the document when the ghost was made. */
+  afterSeq: number
+  until: number
+}
+
+const TTL = 15_000
+
+export function useGhosts(snap: SessionSnapshot | null) {
+  const [ghosts, setGhosts] = useState<Ghost[]>([])
+
+  const add = useCallback((g: Omit<Ghost, 'id' | 'until' | 'afterSeq'>, afterSeq: number) => {
+    const now = Date.now()
+    setGhosts((gs) => [
+      ...gs.filter((x) => !(x.key === g.key && x.path === g.path)),
+      { ...g, afterSeq, id: `${now}-${Math.random().toString(36).slice(2)}`, until: now + TTL },
+    ])
+  }, [])
+
+  /** The page re-rendered after save `seq` of document `key`. */
+  const rendered = useCallback((key: string, seq: number) => {
+    setGhosts((gs) =>
+      gs.some((g) => g.key === key && g.afterSeq < seq)
+        ? gs.filter((g) => !(g.key === key && g.afterSeq < seq))
+        : gs,
+    )
+  }, [])
+
+  // Expired ghosts.
+  useEffect(() => {
+    if (!ghosts.length) return
+    const next = Math.min(...ghosts.map((g) => g.until)) - Date.now()
+    const timer = setTimeout(
+      () => setGhosts((gs) => gs.filter((g) => g.until > Date.now())),
+      Math.max(next, 0) + 10,
+    )
+    return () => clearTimeout(timer)
+  }, [ghosts])
+
+  // A failed save will never render: don't cover the page for it.
+  const visible = ghosts.filter((g) => {
+    const status = snap?.docs[g.key]?.save.status
+    return status !== 'error' && status !== 'conflict'
+  })
+
+  return { ghosts: visible, add, rendered }
+}

package/src/editor/usePageEvents.ts

@@ -0,0 +1,161 @@
+'use client'
+
+/**
+ * Page-level input for the editor:
+ *  - click a field to edit it, a row to select it (⌥-click uses the page normally)
+ *  - keyboard: every target is focusable; Enter edits a field or selects a row,
+ *    ⌥↑/⌥↓ move the selected row, ⌥⌫ deletes it, Escape clears; ⌘Z/⇧⌘Z undo/redo
+ *  - a warning before leaving with unsaved changes
+ */
+import { useEvent } from '../useEvent.ts'
+import { moveItem, refKey, removeItem, resolveRow, updateArray } from '@payload-onpage/core'
+import { useEffect } from 'react'
+import { isOurs, isTyping } from '../dom.ts'
+import { isFieldTarget, isRowTarget, targetsAt } from '../targets.ts'
+import type { OnPageContextValue } from '../types.ts'
+
+const FOCUSABLE_FLAG = 'data-onpage-focusable'
+
+export function usePageEvents(ctx: OnPageContextValue | null, root: () => ParentNode | null): void {
+  const onClick = useEvent((e: MouseEvent) => {
+    if (!ctx || e.altKey || e.button !== 0) return
+    const t = e.target
+    if (!(t instanceof Element) || isOurs(t)) return
+    const r = root()
+    if (r && !r.contains(t)) return
+    const { field, rows } = targetsAt(ctx.targets, t)
+    const row = rows[0]
+    const inControl = !!t.closest('a,button,label,summary,[role="button"]')
+    if (row) ctx.setSelected({ key: refKey(row.ref), path: row.path })
+    else if (!field) ctx.setSelected(null)
+    if (
+      field &&
+      ctx.edit(refKey(field.ref), field.path, {
+        point: { x: e.clientX, y: e.clientY },
+        kind: field.kind,
+        anchor: field.el,
+      })
+    ) {
+      e.preventDefault()
+      e.stopPropagation()
+    } else if ((field || row) && inControl) {
+      e.preventDefault() // don't navigate away from the editor by accident
+    }
+  })
+
+  const moveSelected = (dir: -1 | 1 | 'delete') => {
+    if (!ctx?.selected) return false
+    const { key, path } = ctx.selected
+    const state = ctx.snap.docs[key]
+    const info = state?.schema && state.doc ? resolveRow(state.schema, state.doc, path) : null
+    if (!info) return false
+    if (dir === 'delete') {
+      if (info.length <= (info.listField.minRows ?? 0)) return true
+      ctx.session.apply(key, (d) => updateArray(d, info.listPath, (a) => removeItem(a, info.index)))
+      ctx.setSelected(null)
+      return true
+    }
+    const to = info.index + dir
+    if (to < 0 || to >= info.length) return true
+    ctx.session.apply(key, (d) => updateArray(d, info.listPath, (a) => moveItem(a, info.index, to)))
+    ctx.setSelected({ key, path: `${info.listPath}.${to}` })
+    return true
+  }
+
+  const onKey = useEvent((e: KeyboardEvent) => {
+    if (!ctx) return
+    const mod = e.metaKey || e.ctrlKey
+    if (e.key === 'Escape') {
+      ctx.setPanel(null)
+      ctx.setSelected(null)
+      return
+    }
+    if (isTyping(e.target)) return
+    if (mod && e.key.toLowerCase() === 'z') {
+      e.preventDefault()
+      if (e.shiftKey) ctx.session.redo()
+      else ctx.session.undo()
+      return
+    }
+    if (mod && e.key.toLowerCase() === 'y') {
+      e.preventDefault()
+      ctx.session.redo()
+      return
+    }
+    if (
+      e.altKey &&
+      (e.key === 'ArrowUp' || e.key === 'ArrowDown' || e.key === 'Backspace' || e.key === 'Delete')
+    ) {
+      if (moveSelected(e.key === 'ArrowUp' ? -1 : e.key === 'ArrowDown' ? 1 : 'delete'))
+        e.preventDefault()
+      return
+    }
+    if (
+      (e.key === 'Enter' || e.key === 'F2') &&
+      e.target instanceof Element &&
+      e.target.hasAttribute(FOCUSABLE_FLAG)
+    ) {
+      const own = ctx.targets.at(e.target)
+      const field = own.find(isFieldTarget)
+      const row = own.find(isRowTarget)
+      if (field && ctx.edit(refKey(field.ref), field.path, { kind: field.kind, anchor: field.el }))
+        e.preventDefault()
+      else if (row) {
+        ctx.setSelected({ key: refKey(row.ref), path: row.path })
+        e.preventDefault()
+      }
+    }
+  })
+
+  const onFocus = useEvent((e: FocusEvent) => {
+    if (!ctx || !(e.target instanceof Element) || !e.target.hasAttribute(FOCUSABLE_FLAG)) return
+    const row = ctx.targets.at(e.target).find(isRowTarget)
+    if (row) ctx.setSelected({ key: refKey(row.ref), path: row.path })
+  })
+
+  const onUnload = useEvent((e: BeforeUnloadEvent) => {
+    if (!ctx?.session.hasPendingSaves) return
+    void ctx.session.flush()
+    e.preventDefault()
+  })
+
+  useEffect(() => {
+    document.documentElement.setAttribute('data-onpage-editing', '')
+    const click = (e: MouseEvent) => onClick(e)
+    const key = (e: KeyboardEvent) => onKey(e)
+    const focus = (e: FocusEvent) => onFocus(e)
+    const unload = (e: BeforeUnloadEvent) => onUnload(e)
+    document.addEventListener('click', click, true)
+    document.addEventListener('keydown', key)
+    document.addEventListener('focusin', focus)
+    window.addEventListener('beforeunload', unload)
+    return () => {
+      document.documentElement.removeAttribute('data-onpage-editing')
+      document.removeEventListener('click', click, true)
+      document.removeEventListener('keydown', key)
+      document.removeEventListener('focusin', focus)
+      window.removeEventListener('beforeunload', unload)
+    }
+  }, [onClick, onFocus, onKey, onUnload])
+
+  // Make every target reachable by keyboard (restored when the editor goes away).
+  const targets = ctx?.targets
+  useEffect(() => {
+    const touched: HTMLElement[] = []
+    for (const t of targets?.all ?? []) {
+      if (t.kind === 'list' || !(t.el instanceof HTMLElement) || t.el.hasAttribute('tabindex'))
+        continue
+      t.el.setAttribute('tabindex', '0')
+      t.el.setAttribute(FOCUSABLE_FLAG, '')
+      if (t.label) t.el.setAttribute('aria-description', t.label)
+      touched.push(t.el)
+    }
+    return () => {
+      for (const el of touched) {
+        el.removeAttribute('tabindex')
+        el.removeAttribute(FOCUSABLE_FLAG)
+        el.removeAttribute('aria-description')
+      }
+    }
+  }, [targets])
+}

package/src/editor-kit.ts

@@ -0,0 +1,27 @@
+/**
+ * @payload-onpage/react/editor-kit — building blocks for custom field editors
+ * (the default editors and @payload-onpage/lexical use exactly these).
+ *
+ *   function JsonEditor({ field, value, element, commit, close, t }: FieldEditorProps) {
+ *     return <Dialog variant="popover" anchor={element} title={field.label} onClose={close} t={t}>…</Dialog>
+ *   }
+ */
+export { Dialog, type DialogProps } from './ui/Dialog.tsx'
+export { useOnPage } from './context.tsx'
+export { useDebouncedSearch } from './editors/useDebouncedSearch.ts'
+export { escapeHtml } from './editors/InlineText.tsx'
+export {
+  HIDDEN,
+  UI,
+  caretAt,
+  copyTypography,
+  placeCaret,
+  placeOver,
+  typographyOf,
+  popoverPosition,
+} from './dom.ts'
+export { useTrackElement, useLayoutTick, notifyLayout } from './layout.ts'
+export { useEvent } from './useEvent.ts'
+export { sanitizeHtml } from './sanitize.ts'
+export type { EditorRegistry, FieldEditorDef, FieldEditorProps } from './types.ts'
+export type { Translate } from './messages.ts'

package/src/editors/CheckboxEditor.tsx

@@ -0,0 +1,31 @@
+'use client'
+
+import type { FieldEditorProps } from '../types.ts'
+import { Dialog } from '../ui/Dialog.tsx'
+
+export function CheckboxEditor({ field, value, element, commit, close, t }: FieldEditorProps) {
+  return (
+    <Dialog
+      variant="popover"
+      anchor={element}
+      title={field.label}
+      onClose={close}
+      t={t}
+      testId="onpage-checkbox"
+    >
+      <label className="po-check">
+        <input
+          type="checkbox"
+          data-autofocus
+          checked={Boolean(value ?? field.defaultValue)}
+          onChange={(e) => {
+            commit(e.target.checked)
+            close()
+          }}
+          data-testid="onpage-checkbox-input"
+        />
+        {field.label}
+      </label>
+    </Dialog>
+  )
+}