@payload-onpage/react 0.2.1 → 0.3.1

package/dist/useIsClient.d.ts

@@ -0,0 +1,5 @@
+/** False during SSR and hydration, true after: for UI that only exists in the browser. */
+export declare const useIsClient: () => boolean;
+/** Adds the editor's stylesheet to the page while mounted. */
+export declare const useEditorStyles: () => void;
+//# sourceMappingURL=useIsClient.d.ts.map

package/dist/useIsClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useIsClient.d.ts","sourceRoot":"","sources":["../src/useIsClient.ts"],"names":[],"mappings":"AAKA,0FAA0F;AAC1F,eAAO,MAAM,WAAW,QAAO,OAK5B,CAAA;AAEH,8DAA8D;AAC9D,eAAO,MAAM,eAAe,QAAO,IAA2C,CAAA"}

package/dist/useIsClient.js

@@ -0,0 +1,8 @@
+import { useEffect, useSyncExternalStore } from 'react';
+import { injectStyles } from "./styles.js";
+const noopSubscribe = () => () => { };
+/** False during SSR and hydration, true after: for UI that only exists in the browser. */
+export const useIsClient = () => useSyncExternalStore(noopSubscribe, () => true, () => false);
+/** Adds the editor's stylesheet to the page while mounted. */
+export const useEditorStyles = () => useEffect(() => injectStyles(), []);
+//# sourceMappingURL=useIsClient.js.map

package/dist/useIsClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useIsClient.js","sourceRoot":"","sources":["../src/useIsClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAA;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C,MAAM,aAAa,GAAG,GAAG,EAAE,CAAC,GAAG,EAAE,GAAE,CAAC,CAAA;AAEpC,0FAA0F;AAC1F,MAAM,CAAC,MAAM,WAAW,GAAG,GAAY,EAAE,CACvC,oBAAoB,CAClB,aAAa,EACb,GAAG,EAAE,CAAC,IAAI,EACV,GAAG,EAAE,CAAC,KAAK,CACZ,CAAA;AAEH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,eAAe,GAAG,GAAS,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,YAAY,EAAE,EAAE,EAAE,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payload-onpage/react",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "payload-onpage React editor: overlay, toolbars, field editors, annotations and client mode.",
   "license": "MIT",
   "type": "module",
@@ -15,12 +15,23 @@
   "keywords": [
     "payload",
     "payloadcms",
+    "payload-cms",
     "payload-plugin",
     "nextjs",
+    "next.js",
+    "app-router",
     "visual-editing",
-    "live-preview",
+    "visual-editor",
     "inline-editing",
-    "cms"
+    "front-end-editing",
+    "live-preview",
+    "draft-preview",
+    "preview-links",
+    "page-builder",
+    "wysiwyg",
+    "headless-cms",
+    "cms",
+    "react"
   ],
   "exports": {
     ".": {
@@ -61,7 +72,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@payload-onpage/core": "0.2.1"
+    "@payload-onpage/core": "0.3.1"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/OnPageClient.tsx

@@ -12,10 +12,11 @@
  * invisible markers (turn off with `autoMap={false}`).
  */
 import { useEvent } from './useEvent.ts'
+import { toRef } from './annotations.ts'
 import { encodeDocument, refKey, type DocRef } from '@payload-onpage/core'
 import { useEffect, useMemo, type ReactNode } from 'react'
 import { editable, editableOff, type Editable } from './annotations.ts'
-import { useOnPageOptional } from './context.tsx'
+import { useOnPageOptional, useSessionSnapshot } from './context.tsx'
 
 export type OnPageClientProps<T> = {
   doc: T
@@ -33,9 +34,9 @@ export function OnPageClient<T extends { id?: string | number } | null | undefin
   const ref = useMemo<DocRef | null>(
     () =>
       globalSlug
-        ? { kind: 'global', slug: globalSlug }
-        : collection && id != null
-          ? { kind: 'collection', slug: collection, id }
+        ? toRef({ global: globalSlug })
+        : collection
+          ? toRef({ collection, doc: { id } })
           : null,
     [globalSlug, collection, id],
   )
@@ -51,7 +52,8 @@ export function OnPageClient<T extends { id?: string | number } | null | undefin
   })
   useEffect(() => (enabled && ref ? join(ref) : undefined), [enabled, ref, join])
 
-  const state = key ? ctx?.snap.docs[key] : undefined
+  const snap = useSessionSnapshot(ctx?.session)
+  const state = key ? snap.docs[key] : undefined
   const stateDoc = state?.doc
   const fields = state?.schema?.fields
   const autoMap = props.autoMap !== false
@@ -63,5 +65,7 @@ export function OnPageClient<T extends { id?: string | number } | null | undefin
     () => (enabled && ref ? editable(ref, { enabled: true }) : editableOff),
     [enabled, ref],
   )
+  // The session's copy started as this `doc` (same document, edited, held as plain JSON),
+  // so it is handed back as the page's own type.
   return <>{render(current as T, e)}</>
 }

package/src/annotations.ts

@@ -51,7 +51,7 @@ export const editableOff: Editable = {
 
 export type EditableTarget =
   | DocRef
-  | { collection: string; doc: { id?: string | number } | null | undefined }
+  | { collection: string; doc: { id?: string | number | undefined } | null | undefined }
   | { global: string }
 
 export function toRef(t: EditableTarget): DocRef | null {

package/src/context.tsx

@@ -1,23 +1,66 @@
 'use client'
 
-import { createContext, useContext, useSyncExternalStore } from 'react'
+import { createContext, useContext, useSyncExternalStore, type ReactNode } from 'react'
+import type { EditorSession, SessionSnapshot } from '@payload-onpage/core'
 import { hub } from './hub.ts'
-import type { OnPageContextValue } from './types.ts'
+import type { OnPageApi, OnPageContextValue, OnPageState } from './types.ts'
 
-export const OnPageContext = createContext<OnPageContextValue | null>(null)
+const ApiContext = createContext<OnPageApi | null>(null)
+const StateContext = createContext<OnPageState | null>(null)
 
-/** The editor, for code rendered inside it (field editors, panels). */
+/** Provides the editor to everything it renders (two contexts: the stable API and the changing state). */
+export function OnPageProvider({
+  api,
+  state,
+  children,
+}: {
+  api: OnPageApi
+  state: OnPageState
+  children: ReactNode
+}) {
+  return (
+    <ApiContext.Provider value={api}>
+      <StateContext.Provider value={state}>{children}</StateContext.Provider>
+    </ApiContext.Provider>
+  )
+}
+
+/** The editor, for code rendered inside it (field editors, panels): its API and state. */
 export function useOnPage(): OnPageContextValue {
-  const ctx = useContext(OnPageContext)
-  if (!ctx) throw new Error('useOnPage must be used inside <OnPageEditor>')
-  return ctx
+  const api = useContext(ApiContext)
+  const state = useContext(StateContext)
+  if (!api || !state) throw new Error('useOnPage must be used inside <OnPageEditor>')
+  return { ...api, ...state }
+}
+
+/** Only the editor's API (session, actions): re-renders when the editor is reconfigured, not on every edit. */
+export function useOnPageApi(): OnPageApi {
+  const api = useContext(ApiContext)
+  if (!api) throw new Error('useOnPageApi must be used inside <OnPageEditor>')
+  return api
 }
 
 const getNull = () => null
 
-/** The editor, from inside it or anywhere on the page; null when no editor is mounted (public pages). */
-export function useOnPageOptional(): OnPageContextValue | null {
-  const inside = useContext(OnPageContext)
+/**
+ * The editor's API from inside it or anywhere on the page; null when no editor
+ * is mounted (public pages). Read documents with `useSessionSnapshot(api?.session)`.
+ */
+export function useOnPageOptional(): OnPageApi | null {
+  const inside = useContext(ApiContext)
   const outside = useSyncExternalStore(hub.subscribe, hub.get, getNull)
   return inside ?? outside
 }
+
+const EMPTY: SessionSnapshot = { docs: {}, canUndo: false, canRedo: false, busy: false }
+const noopSubscribe = () => () => {}
+const getEmpty = () => EMPTY
+
+/** A session's documents, re-rendering when they change (an empty snapshot without a session). */
+export function useSessionSnapshot(session: EditorSession | null | undefined): SessionSnapshot {
+  return useSyncExternalStore(
+    session?.subscribe ?? noopSubscribe,
+    session?.getSnapshot ?? getEmpty,
+    getEmpty,
+  )
+}

package/src/dom.ts

@@ -1,9 +1,21 @@
 /** DOM helpers shared by the editor UI (browser-only, no React). */
 
-/** Attribute that hides a page element while an editor or ghost stands in for it. */
-export const HIDDEN = 'data-onpage-hidden'
-/** Marks the editor's own UI, which locators and click handling ignore. */
-export const UI = 'data-onpage-ui'
+/** Every DOM attribute the editor sets (annotations, which sites write, are `ATTR`). */
+export const DOM_ATTR = {
+  /** Hides a page element while an editor or ghost stands in for it. */
+  hidden: 'data-onpage-hidden',
+  /** Marks the editor's own UI, which locators and click handling ignore. */
+  ui: 'data-onpage-ui',
+  /** A page target the editor made keyboard-focusable. */
+  focusable: 'data-onpage-focusable',
+  /** On <html> while editing. */
+  editing: 'data-onpage-editing',
+  /** The editor's injected stylesheet. */
+  styles: 'data-onpage-styles',
+} as const
+
+export const HIDDEN = DOM_ATTR.hidden
+export const UI = DOM_ATTR.ui
 
 /** Computed styles copied onto an inline editor so it looks like the element it replaces. */
 export const TYPOGRAPHY = [
@@ -94,20 +106,7 @@ export function placeCaret(el: HTMLElement, point?: { x: number; y: number }): v
   sel.addRange(range)
 }
 
-/** Position a fixed popover below (or above) an element, kept inside the viewport. */
-export function popoverPosition(
-  el: Element | null,
-  size = { width: 300, height: 320 },
-): { top: number; left: number } {
-  const vw = window.innerWidth
-  const vh = window.innerHeight
-  if (!el) return { top: 80, left: Math.max(8, vw / 2 - size.width / 2) }
-  const r = el.getBoundingClientRect()
-  const below = r.bottom + 8
-  const top = below + size.height < vh ? below : Math.max(8, r.top - 8 - size.height)
-  const left = Math.min(Math.max(8, r.left), vw - size.width - 8)
-  return { top, left }
-}
+export { popoverPosition } from './geometry.ts'
 
 const FOCUSABLE =
   'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])'

package/src/editor/FieldHost.tsx

@@ -1,19 +1,34 @@
 'use client'
 
-import { fieldAtPath, getAt } from '@payload-onpage/core'
+import { fieldAtPath, getAt, isReady, type ReadyDocumentState } from '@payload-onpage/core'
 import { Suspense, useCallback } from 'react'
 import { useOnPage } from '../context.tsx'
-import type { FieldEditorProps } from '../types.ts'
+import { canEdit } from '../registry.ts'
+import type { EditingState, FieldEditorDef, FieldEditorProps } from '../types.ts'
 
 /** Renders the open field editor, if it belongs to this layer. */
 export function FieldHost({ mode }: { mode: 'inline' | 'popover' }) {
-  const { editing, editors, session, snap, targets, setEditing, addGhost, isLive, t } = useOnPage()
-  const def = editing ? editors[editing.editor] : undefined
-  const state = editing ? snap.docs[editing.key] : undefined
-  const key = editing?.key ?? ''
-  const path = editing?.path ?? ''
+  const { editing, editors, snap } = useOnPage()
+  if (!editing) return null
+  const def = editors[editing.editor]
+  const state = snap.docs[editing.key]
+  if (!def || def.mode !== mode || !isReady(state)) return null
+  return <OpenEditor editing={editing} def={def} state={state} />
+}
+
+/** The editor for one field of a loaded document. */
+function OpenEditor({
+  editing,
+  def,
+  state,
+}: {
+  editing: EditingState
+  def: FieldEditorDef
+  state: ReadyDocumentState
+}) {
+  const { session, targets, setEditing, addGhost, isLive, t } = useOnPage()
+  const { key, path, el: clicked } = editing
   const live = isLive(key)
-  const clicked = editing?.el
 
   const element = useCallback(
     () => (clicked?.isConnected ? clicked : (targets.find(key, path)?.el ?? null)),
@@ -39,10 +54,10 @@ export function FieldHost({ mode }: { mode: 'inline' | 'popover' }) {
     [addGhost, key, path],
   )
 
-  if (!editing || !def || def.mode !== mode || !state?.schema || !state.doc) return null
   const field = fieldAtPath(state.schema.fields, state.doc, path)?.field
-  if (!field) return null
+  if (!field || !canEdit(def, field)) return null
   const Editor = def.component
+  const raw = getAt(state.doc, path)
   // Editors may be lazy (the rich-text editor is): render nothing until they've loaded.
   return (
     <Suspense fallback={null}>
@@ -52,7 +67,7 @@ export function FieldHost({ mode }: { mode: 'inline' | 'popover' }) {
         path={path}
         field={field}
         element={element}
-        value={getAt(state.doc, path)}
+        value={def.normalize ? def.normalize(raw, field) : raw}
         commit={commit}
         preview={preview}
         close={close}