@payload-onpage/react 0.2.1 → 0.3.1

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 = `
@@ -51,14 +52,14 @@ export const PO_CSS = `
 .po-blocks{display:grid;grid-template-columns:repeat(auto-fill,minmax(180px,1fr));gap:10px}
 .po-blocks button{all:unset;padding:14px;border:1px solid #e2e8f0;border-radius:10px;cursor:pointer;font:600 13px system-ui,sans-serif}
 .po-blocks button:hover,.po-blocks button:focus-visible{border-color:#4f7cff;background:#f5f8ff}
-.po-dock{position:fixed;left:50%;bottom:16px;transform:translateX(-50%);display:flex;align-items:center;gap:4px;padding:6px;background:#0f172a;color:#fff;border-radius:12px;box-shadow:0 12px 40px #0f172a55;pointer-events:auto;max-width:calc(100vw - 24px);flex-wrap:wrap}
+.po-dock{position:fixed;left:50%;width:max-content;bottom:16px;transform:translateX(-50%);display:flex;align-items:center;gap:4px;padding:6px;background:#0f172a;color:#fff;border-radius:12px;box-shadow:0 12px 40px #0f172a55;pointer-events:auto;max-width:calc(100vw - 24px);flex-wrap:wrap}
 .po-dock .po-status{padding:0 10px;font-size:12px;opacity:.85;white-space:nowrap}
 .po-dock .po-status.is-bad{color:#fca5a5;opacity:1}
 .po-dock .po-sep{width:1px;height:20px;background:#ffffff26;margin:0 4px}
 .po-dock .po-primary{background:#3b63e0}
 .po-dock .po-primary:hover{background:#2f5bd9}
 .po-chip-locale{padding:2px 7px;border-radius:999px;background:#ffffff1f;font-size:11px;font-weight:700;text-transform:uppercase}
-.po-notice{position:fixed;left:50%;bottom:72px;transform:translateX(-50%);max-width:min(560px,calc(100vw - 24px));padding:8px 12px;border-radius:10px;background:#fffbeb;color:#78350f;border:1px solid #fcd34d;font-size:12px;pointer-events:auto}
+.po-notice{position:fixed;left:50%;width:max-content;bottom:72px;transform:translateX(-50%);max-width:min(560px,calc(100vw - 24px));padding:8px 12px;border-radius:10px;background:#fffbeb;color:#78350f;border:1px solid #fcd34d;font-size:12px;pointer-events:auto}
 .po-doc-layer{position:absolute;top:0;left:0;width:0;height:0;overflow:visible;z-index:${PO_Z};pointer-events:none;font:13px/1.35 system-ui,-apple-system,"Segoe UI",sans-serif}
 .po-inline{position:absolute;pointer-events:auto;outline:2px solid #4f7cff;outline-offset:2px;border-radius:2px;background:transparent;white-space:pre-wrap;word-break:break-word;caret-color:currentColor;cursor:text}
 .po-inline:focus{outline-color:#4f7cff}
@@ -81,7 +82,7 @@ export const PO_CSS = `
 .po-opaque{display:inline-flex;align-items:center;gap:6px;margin:6px 0;padding:6px 10px;border:1px dashed #94a3b8;border-radius:8px;background:#f8fafc;color:#475569;font:12px system-ui,sans-serif;user-select:none}
 html[data-onpage-editing] [data-onpage-field]{cursor:pointer}
 [data-onpage-hidden="true"]{visibility:hidden!important}
-.po-preview{position:fixed;left:50%;bottom:16px;transform:translateX(-50%);display:flex;align-items:center;gap:6px;padding:6px;background:#0f172a;color:#fff;border-radius:12px;box-shadow:0 12px 40px #0f172a55;pointer-events:auto;max-width:calc(100vw - 24px);flex-wrap:wrap}
+.po-preview{position:fixed;left:50%;width:max-content;bottom:16px;transform:translateX(-50%);display:flex;align-items:center;gap:6px;padding:6px;background:#0f172a;color:#fff;border-radius:12px;box-shadow:0 12px 40px #0f172a55;pointer-events:auto;max-width:calc(100vw - 24px);flex-wrap:wrap}
 .po-preview .po-status{padding:0 8px;font-size:12px;opacity:.85}
 .po-rel-item{display:flex;align-items:center;gap:6px;padding:4px 6px;border-radius:6px;background:#f1f5f9;font-size:12px;margin:0 0 4px}
 .po-rel-item button{all:unset;cursor:pointer;margin-left:auto;padding:0 4px;color:#64748b}
@@ -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">

package/src/ui/Dock.tsx

@@ -5,14 +5,49 @@
  * recovery: reload after a conflict, retry after an error), undo/redo, locale,
  * share link, preview, discard, admin, exit and publish.
  */
+import { errorText } from '@payload-onpage/core'
 import type { DocumentState } from '@payload-onpage/core'
 import { useEffect, useState } from 'react'
 import { useOnPage } from '../context.tsx'
-import { relativeTime } from '../messages.ts'
+import { relativeTime, type Translate } from '../messages.ts'
 import { PostButton } from './PostButton.tsx'
+import { ToolbarButton } from './ToolbarButton.tsx'
+import type { Flash } from '../types.ts'
 
 const title = (d: DocumentState) => d.schema?.labels.singular ?? d.ref.slug
 
+interface DockState {
+  docs: DocumentState[]
+  ready: DocumentState[]
+  failed: DocumentState | undefined
+  conflict: DocumentState | undefined
+  error: DocumentState | undefined
+  saving: boolean
+  rendering: boolean
+  lastSaved: number
+}
+
+/** What the dock says, most urgent first. */
+function dockStatus(s: DockState, t: Translate): Flash {
+  if (s.failed)
+    return {
+      text: t('dock.unavailable', { doc: title(s.failed), error: s.failed.error ?? '' }),
+      bad: true,
+    }
+  if (!s.docs.length) return { text: t('dock.nothing') }
+  if (!s.ready.length) return { text: t('dock.loading') }
+  if (s.conflict) return { text: t('dock.conflict', { doc: title(s.conflict) }), bad: true }
+  if (s.error)
+    return {
+      text: t('dock.saveFailed', { doc: title(s.error), message: s.error.save.message ?? '' }),
+      bad: true,
+    }
+  if (s.saving) return { text: t('dock.saving') }
+  if (s.rendering) return { text: t('dock.updating') }
+  if (s.lastSaved) return { text: t('dock.saved', { ago: relativeTime(s.lastSaved) }) }
+  return { text: t('dock.editing') }
+}
+
 function useTicker(ms: number) {
   const [, setN] = useState(0)
   useEffect(() => {
@@ -21,8 +56,8 @@ function useTicker(ms: number) {
   }, [ms])
 }
 
-export function Dock({ flash }: { flash: { text: string; bad?: boolean } | null }) {
-  const { session, snap, links, rendering, notify, rerender, docKeys, t } = useOnPage()
+export function Dock() {
+  const { session, snap, links, rendering, notify, rerender, docKeys, flash, t } = useOnPage()
   const [confirmDiscard, setConfirmDiscard] = useState(false)
   useTicker(5000)
   useEffect(() => {
@@ -41,23 +76,11 @@ export function Dock({ flash }: { flash: { text: string; bad?: boolean } | null
   const primary = docs[0]
   const busy = snap.busy
 
-  const status = failed
-    ? { text: t('dock.unavailable', { doc: title(failed), error: failed.error ?? '' }), bad: true }
-    : !docs.length
-      ? { text: t('dock.nothing') }
-      : !ready.length
-        ? { text: t('dock.loading') }
-        : conflict
-          ? { text: t('dock.conflict', { doc: title(conflict) }), bad: true }
-          : error
-            ? { text: `${title(error)}: ${error.save.message ?? ''}`, bad: true }
-            : saving
-              ? { text: t('dock.saving') }
-              : rendering
-                ? { text: t('dock.updating') }
-                : lastSaved
-                  ? { text: t('dock.saved', { ago: relativeTime(lastSaved) }) }
-                  : { text: t('dock.editing') }
+  const retryable = failed ?? error
+  const status = dockStatus(
+    { docs, ready, failed, conflict, error, saving, rendering, lastSaved },
+    t,
+  )
 
   const schema = ready[0]?.schema
   const nonDefaultLocale =
@@ -67,10 +90,10 @@ export function Dock({ flash }: { flash: { text: string; bad?: boolean } | null
     try {
       const res = await session.publish({ keys: docKeys })
       if (res.published.length) await rerender(res.published)
-      if (res.ok) notify(res.published.length ? 'notify.published' : 'notify.nothingToPublish')
-      else notify('notify.publishFailed', { message: res.message ?? '' }, true)
+      if (res.ok) notify(t(res.published.length ? 'notify.published' : 'notify.nothingToPublish'))
+      else notify(t('notify.publishFailed', { message: res.message ?? '' }), true)
     } catch (e) {
-      notify('notify.publishFailed', { message: (e as Error).message }, true)
+      notify(t('notify.publishFailed', { message: errorText(e) }), true)
     }
   }
   const discard = async () => {
@@ -79,9 +102,9 @@ export function Dock({ flash }: { flash: { text: string; bad?: boolean } | null
     setConfirmDiscard(false)
     try {
       await session.discard({ keys: docKeys })
-      notify('notify.discarded')
+      notify(t('notify.discarded'))
     } catch (e) {
-      notify((e as Error).message, undefined, true)
+      notify(errorText(e), true)
     }
   }
   const reload = async (d: DocumentState) => {
@@ -89,7 +112,7 @@ export function Dock({ flash }: { flash: { text: string; bad?: boolean } | null
       await session.reload(d.key)
       await rerender([d.ref])
     } catch (e) {
-      notify((e as Error).message, undefined, true)
+      notify(errorText(e), true)
     }
   }
   const createLink = session.dataSource.createPreviewLink?.bind(session.dataSource)
@@ -98,9 +121,9 @@ export function Dock({ flash }: { flash: { text: string; bad?: boolean } | null
     try {
       const { url, expiresAt } = await createLink(primary.ref, { locale: session.locale })
       await navigator.clipboard.writeText(url)
-      notify('notify.linkCopied', { date: new Date(expiresAt).toLocaleString() })
+      notify(t('notify.linkCopied', { date: new Date(expiresAt).toLocaleString() }))
     } catch (e) {
-      notify('notify.linkFailed', { message: (e as Error).message }, true)
+      notify(t('notify.linkFailed', { message: errorText(e) }), true)
     }
   }
 
@@ -136,11 +159,11 @@ export function Dock({ flash }: { flash: { text: string; bad?: boolean } | null
             {t('dock.reload')}
           </button>
         )}
-        {(failed ?? error) && (
+        {retryable && (
           <button
             type="button"
             className="po-btn"
-            onClick={() => void session.retry((failed ?? error)!.key)}
+            onClick={() => void session.retry(retryable.key)}
             data-testid="onpage-retry"
           >
             {t('dock.retry')}
@@ -157,28 +180,22 @@ export function Dock({ flash }: { flash: { text: string; bad?: boolean } | null
         )}
         {session.locale && <span className="po-chip-locale">{session.locale}</span>}
         <span className="po-sep" />
-        <button
-          type="button"
-          className="po-btn"
-          onClick={() => session.undo()}
+        <ToolbarButton
+          label={t('dock.undo')}
+          hint={`${t('dock.undo')} (⌘Z)`}
+          icon="↶"
           disabled={!snap.canUndo}
-          aria-label={t('dock.undo')}
-          title={`${t('dock.undo')} (⌘Z)`}
-          data-testid="onpage-undo"
-        >
-          ↶
-        </button>
-        <button
-          type="button"
-          className="po-btn"
-          onClick={() => session.redo()}
+          onClick={() => session.undo()}
+          testId="onpage-undo"
+        />
+        <ToolbarButton
+          label={t('dock.redo')}
+          hint={`${t('dock.redo')} (⇧⌘Z)`}
+          icon="↷"
           disabled={!snap.canRedo}
-          aria-label={t('dock.redo')}
-          title={`${t('dock.redo')} (⇧⌘Z)`}
-          data-testid="onpage-redo"
-        >
-          ↷
-        </button>
+          onClick={() => session.redo()}
+          testId="onpage-redo"
+        />
         <span className="po-sep" />
         {links.mode && (
           <PostButton