@payload-onpage/react 0.2.0 → 0.3.0

package/src/editors/SelectEditor.tsx

@@ -1,20 +1,19 @@
 'use client'
 
-import { toText } from '@payload-onpage/core'
+import { asList, type ChoiceField } from '@payload-onpage/core'
 import type { FieldEditorProps } from '../types.ts'
-import { Dialog } from '../ui/Dialog.tsx'
+import { EditorPopover } from './kit.tsx'
+
+/** A select/radio value as the selected option values. */
+export const selectedValues = (raw: unknown, field: ChoiceField): string[] =>
+  asList(raw, field.hasMany, (v) =>
+    typeof v === 'string' || typeof v === 'number' ? String(v) : undefined,
+  )
 
 /** Select / radio: pick one (closes) or toggle several (hasMany). */
-export function SelectEditor({ field, value, element, commit, close, t }: FieldEditorProps) {
-  const options = field.options ?? []
+export function SelectEditor(props: FieldEditorProps<ChoiceField, string[]>) {
+  const { field, value: current, commit, close, t } = props
   const many = !!field.hasMany
-  const current: string[] = many
-    ? Array.isArray(value)
-      ? (value as string[])
-      : []
-    : value == null
-      ? []
-      : [toText(value)]
   const pick = (v: string | null) => {
     if (!many) {
       commit(v)
@@ -25,17 +24,10 @@ export function SelectEditor({ field, value, element, commit, close, t }: FieldE
     if (v === null) set.clear()
     else if (set.has(v)) set.delete(v)
     else set.add(v)
-    commit(options.map((o) => o.value).filter((o) => set.has(o)))
+    commit(field.options.map((o) => o.value).filter((o) => set.has(o)))
   }
   return (
-    <Dialog
-      variant="popover"
-      anchor={element}
-      title={field.label}
-      onClose={close}
-      t={t}
-      testId="onpage-select"
-    >
+    <EditorPopover props={props} testId="onpage-select">
       <div
         className="po-pop-list"
         role="listbox"
@@ -52,7 +44,7 @@ export function SelectEditor({ field, value, element, commit, close, t }: FieldE
             {t('common.none')}
           </button>
         )}
-        {options.map((o) => {
+        {field.options.map((o) => {
           const selected = current.includes(o.value)
           return (
             <button
@@ -69,6 +61,6 @@ export function SelectEditor({ field, value, element, commit, close, t }: FieldE
           )
         })}
       </div>
-    </Dialog>
+    </EditorPopover>
   )
 }

package/src/editors/UploadEditor.tsx

@@ -5,14 +5,14 @@
  * new file, through the MediaLibrary port. The chosen document goes into state
  * populated, so a client-rendered page shows it at once; saving sends its id.
  */
-import { relationId, type MediaItem } from '@payload-onpage/core'
+import { errorText, relationId, type MediaItem, type RelationField } from '@payload-onpage/core'
 import { useCallback, useRef, useState } from 'react'
 import { useOnPage } from '../context.tsx'
 import type { FieldEditorProps } from '../types.ts'
 import { Dialog } from '../ui/Dialog.tsx'
 import { useDebouncedSearch } from './useDebouncedSearch.ts'
 
-export function UploadEditor({ field, value, commit, close, t }: FieldEditorProps) {
+export function UploadEditor({ field, value, commit, close, t }: FieldEditorProps<RelationField>) {
   const { media } = useOnPage()
   const relationTo =
     (Array.isArray(field.relationTo) ? field.relationTo[0] : field.relationTo) ?? 'media'
@@ -20,13 +20,13 @@ export function UploadEditor({ field, value, commit, close, t }: FieldEditorProp
   const [uploadError, setUploadError] = useState<string | null>(null)
   const fileRef = useRef<HTMLInputElement>(null)
   const search = useCallback(
-    (query: string, page: number) =>
+    (query: string, page: number, signal: AbortSignal) =>
       media
-        ? media.search({ query, page, relationTo })
+        ? media.search({ query, page, relationTo, signal })
         : Promise.resolve({ items: [] as MediaItem[], hasMore: false }),
     [media, relationTo],
   )
-  const results = useDebouncedSearch<MediaItem>(media ? search : null, [])
+  const results = useDebouncedSearch<MediaItem>(media ? search : null)
   const currentId = relationId(value)
 
   const choose = (m: MediaItem) => {
@@ -39,7 +39,7 @@ export function UploadEditor({ field, value, commit, close, t }: FieldEditorProp
     try {
       choose(await media.upload(file, { relationTo }))
     } catch (e) {
-      setUploadError((e as Error).message)
+      setUploadError(errorText(e))
     } finally {
       setUploading(false)
     }

package/src/editors/index.ts

@@ -1,26 +1,66 @@
 /** The default field editors. Spread, override or remove (`null`) entries via the `editors` option. */
+import { toText } from '@payload-onpage/core'
+import { defineEditor } from '../registry.ts'
 import type { EditorRegistry } from '../types.ts'
-import { CheckboxEditor } from './CheckboxEditor.tsx'
-import { ColorEditor } from './ColorEditor.tsx'
-import { DateEditor } from './DateEditor.tsx'
+import { checkedOf, CheckboxEditor } from './CheckboxEditor.tsx'
+import { ColorEditor, toColor } from './ColorEditor.tsx'
+import { DateEditor, toIsoDate } from './DateEditor.tsx'
 import { InlineText } from './InlineText.tsx'
-import { NumberEditor } from './NumberEditor.tsx'
+import { NumberEditor, toNumber } from './NumberEditor.tsx'
 import { RelationshipEditor } from './RelationshipEditor.tsx'
-import { SelectEditor } from './SelectEditor.tsx'
+import { SelectEditor, selectedValues } from './SelectEditor.tsx'
 import { UploadEditor } from './UploadEditor.tsx'
 
+const text = defineEditor({
+  mode: 'inline',
+  accepts: ['text', 'textarea', 'email'],
+  normalize: (raw) => toText(raw),
+  component: InlineText,
+})
+const select = defineEditor({
+  mode: 'popover',
+  accepts: ['select', 'radio'],
+  normalize: selectedValues,
+  component: SelectEditor,
+})
+
 export const defaultEditors: EditorRegistry = {
-  text: { mode: 'inline', component: InlineText },
-  textarea: { mode: 'inline', component: InlineText },
-  email: { mode: 'inline', component: InlineText },
-  select: { mode: 'popover', component: SelectEditor },
-  radio: { mode: 'popover', component: SelectEditor },
-  checkbox: { mode: 'popover', component: CheckboxEditor },
-  number: { mode: 'popover', component: NumberEditor },
-  date: { mode: 'popover', component: DateEditor },
-  relationship: { mode: 'popover', component: RelationshipEditor },
-  upload: { mode: 'popover', component: UploadEditor },
-  color: { mode: 'popover', component: ColorEditor },
+  text,
+  textarea: text,
+  email: text,
+  select,
+  radio: select,
+  checkbox: defineEditor({
+    mode: 'popover',
+    accepts: ['checkbox'],
+    normalize: checkedOf,
+    component: CheckboxEditor,
+  }),
+  number: defineEditor({
+    mode: 'popover',
+    accepts: ['number'],
+    normalize: toNumber,
+    component: NumberEditor,
+  }),
+  date: defineEditor({
+    mode: 'popover',
+    accepts: ['date'],
+    normalize: toIsoDate,
+    component: DateEditor,
+  }),
+  relationship: defineEditor({
+    mode: 'popover',
+    accepts: ['relationship'],
+    component: RelationshipEditor,
+  }),
+  upload: defineEditor({ mode: 'popover', accepts: ['upload'], component: UploadEditor }),
+  // A text field holding a hex color: `admin.custom.onpage.editor: 'color'`.
+  color: defineEditor({
+    mode: 'popover',
+    accepts: ['text'],
+    normalize: toColor,
+    component: ColorEditor,
+  }),
 }
 
 export {

package/src/editors/kit.tsx

@@ -0,0 +1,97 @@
+'use client'
+
+/**
+ * The parts every popover editor shares: the anchored dialog, the Apply/Clear
+ * bar, and a draft that previews live and commits once. Exported from
+ * `@payload-onpage/react/editor-kit` for custom editors.
+ */
+import { useState, type ReactNode } from 'react'
+import type { Translate } from '../messages.ts'
+import type { FieldEditorProps } from '../types.ts'
+import { Dialog } from '../ui/Dialog.tsx'
+
+/** The popover a field editor opens beside its element, titled with the field's label. */
+export function EditorPopover({
+  props,
+  testId,
+  width,
+  children,
+}: {
+  props: Pick<FieldEditorProps, 'element' | 'field' | 'close' | 't'>
+  testId: string
+  width?: number
+  children: ReactNode
+}) {
+  return (
+    <Dialog
+      variant="popover"
+      anchor={props.element}
+      title={props.field.label}
+      onClose={props.close}
+      t={props.t}
+      testId={testId}
+      {...(width ? { width } : {})}
+    >
+      {children}
+    </Dialog>
+  )
+}
+
+/** Apply, plus Clear when the field may be empty. */
+export function ApplyBar({
+  onApply,
+  onClear,
+  t,
+}: {
+  onApply: () => void
+  onClear?: (() => void) | undefined
+  t: Translate
+}) {
+  return (
+    <div className="po-actions">
+      <button
+        type="button"
+        className="po-btn po-primary"
+        onClick={onApply}
+        data-testid="onpage-apply"
+      >
+        {t('common.apply')}
+      </button>
+      {onClear && (
+        <button type="button" className="po-btn" onClick={onClear} data-testid="onpage-clear">
+          {t('common.clear')}
+        </button>
+      )}
+    </div>
+  )
+}
+
+/**
+ * A text draft for a value: `parse` turns the draft into a value (undefined =
+ * not valid yet). Valid drafts preview live when the page renders from editor
+ * state; `save` commits only a changed, valid value, then closes.
+ */
+export function useDraft<V>(
+  props: Pick<FieldEditorProps<never, V>, 'value' | 'commit' | 'preview' | 'close' | 'live'>,
+  {
+    format,
+    parse,
+  }: { format: (value: V) => string; parse: (draft: string) => V | null | undefined },
+) {
+  const [draft, setDraft] = useState(() => format(props.value))
+  const change = (next: string) => {
+    setDraft(next)
+    const value = parse(next)
+    if (props.live && value !== undefined && value !== null) props.preview(value)
+  }
+  const save = () => {
+    const value = parse(draft)
+    if (value !== undefined && value !== props.value) props.commit(value)
+    props.close()
+  }
+  /** Enter applies. */
+  const onKeyDown = (e: { key: string }) => {
+    if (e.key === 'Enter') save()
+  }
+  return { draft, change, save, onKeyDown, clear: () => change('') }
+}

package/src/editors/useDebouncedSearch.ts

@@ -1,15 +1,22 @@
 'use client'
 
+import { errorText } from '@payload-onpage/core'
 import { useEffect, useState } from 'react'
 
+/** A search the hook runs: it should stop when `signal` aborts. */
+export type SearchFn<T> = (
+  query: string,
+  page: number,
+  signal: AbortSignal,
+) => Promise<{ items: T[]; hasMore: boolean }>
+
 /**
- * Run `search(query, page)` 250ms after the inputs settle; results accumulate
- * across pages and reset when the query changes. Stale responses are ignored.
+ * Run `search(query, page, signal)` 250ms after the inputs settle; results
+ * accumulate across pages and reset when the query changes. A superseded search
+ * is aborted, and its response ignored. Re-runs when `search` changes, so keep
+ * it stable (`useCallback`) with its inputs as dependencies.
  */
-export function useDebouncedSearch<T>(
-  search: ((query: string, page: number) => Promise<{ items: T[]; hasMore: boolean }>) | null,
-  deps: unknown[],
-) {
+export function useDebouncedSearch<T>(search: SearchFn<T> | null) {
   const [query, setQuery] = useState('')
   const [page, setPage] = useState(1)
   const [items, setItems] = useState<T[]>([])
@@ -20,24 +27,25 @@ export function useDebouncedSearch<T>(
   useEffect(() => {
     if (!search) return
     let live = true
+    const aborter = new AbortController()
     const timer = setTimeout(() => {
       setBusy(true)
-      search(query, page)
+      search(query, page, aborter.signal)
         .then((res) => {
           if (!live) return
           setItems((prev) => (page === 1 ? res.items : [...prev, ...res.items]))
           setHasMore(res.hasMore)
           setError(null)
         })
-        .catch((e: unknown) => live && setError(e instanceof Error ? e.message : String(e)))
+        .catch((e: unknown) => live && !aborter.signal.aborted && setError(errorText(e)))
         .finally(() => live && setBusy(false))
     }, 250)
     return () => {
       live = false
       clearTimeout(timer)
+      aborter.abort()
     }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [search, query, page, ...deps])
+  }, [search, query, page])
 
   return {
     query,

package/src/geometry.ts

@@ -0,0 +1,62 @@
+/**
+ * Where the editor's floating UI goes: named distances (px) and the positioning
+ * rules shared by the overlay, toolbars and popovers.
+ */
+type Rect = Pick<DOMRect, 'top' | 'bottom' | 'left' | 'right' | 'width' | 'height'>
+
+export const GEOMETRY = {
+  /** Gap kept between floating UI and the viewport edge or its element. */
+  margin: 8,
+  /** How far an outline sits outside its element. */
+  outline: 2,
+  /** Height of a row toolbar. */
+  toolbar: 40,
+  /** Toolbars never ride higher than this (the site header usually lives there). */
+  toolbarMinTop: 60,
+  /** Field label chips never go above this. */
+  chipMinTop: 22,
+  /** Gap between a list and its "+ Add" button. */
+  addGap: 14,
+  /** Room left at the bottom for the dock. */
+  dock: 84,
+  /** "+ Add first section" sits at most this far down an empty list. */
+  emptyListOffset: 160,
+} as const
+
+const { margin, outline, toolbar, toolbarMinTop, addGap, dock } = GEOMETRY
+
+/** Is any of the element on screen, `inset` px inside the top and bottom? */
+export const inViewport = (r: Rect, inset = 0): boolean =>
+  r.bottom >= inset && r.top <= window.innerHeight - inset
+
+/** An outline box around an element. */
+export const outlineBox = (r: Rect) => ({
+  top: r.top - outline,
+  left: r.left - outline,
+  width: r.width + 2 * outline,
+  height: r.height + 2 * outline,
+})
+
+/** A row toolbar: top-right inside the row, kept below the header and above the row's end. */
+export const toolbarPosition = (r: Rect) => ({
+  top: Math.min(Math.max(r.top + margin, toolbarMinTop), r.bottom - toolbar),
+  right: Math.max(window.innerWidth - r.right + margin, margin),
+})
+
+/** "+ Add" below a list, or pinned above the dock while the list runs past the viewport. */
+export const belowList = (r: Rect): number => Math.min(r.bottom + addGap, window.innerHeight - dock)
+
+/** A fixed popover below (or, without room, 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(margin, vw / 2 - size.width / 2) }
+  const r = el.getBoundingClientRect()
+  const below = r.bottom + margin
+  const top = below + size.height < vh ? below : Math.max(margin, r.top - margin - size.height)
+  const left = Math.min(Math.max(margin, r.left), vw - size.width - margin)
+  return { top, left }
+}

package/src/hub.ts

@@ -1,14 +1,14 @@
 /**
- * The editor hub: a module-level store holding the mounted editor, so
+ * The editor hub: a module-level store holding the mounted editor's API, so
  * components anywhere on the page (client-mode documents, custom UI) can reach
  * it without being rendered inside it. That keeps `<OnPage />` a sibling in the
  * layout, not a wrapper. Kept on `globalThis` so two copies of the package
  * (a bundling mistake) still share one editor.
  */
-import type { OnPageContextValue } from './types.ts'
+import type { OnPageApi } from './types.ts'
 
 interface Hub {
-  current: OnPageContextValue | null
+  current: OnPageApi | null
   listeners: Set<() => void>
 }
 
@@ -19,8 +19,8 @@ const store: Hub = ((globalThis as Record<symbol, Hub | undefined>)[KEY] ??= {
 })
 
 export const hub = {
-  get: (): OnPageContextValue | null => store.current,
-  set: (value: OnPageContextValue | null): void => {
+  get: (): OnPageApi | null => store.current,
+  set: (value: OnPageApi | null): void => {
     if (value === store.current) return
     store.current = value
     for (const fn of store.listeners) fn()

package/src/index.ts

@@ -14,13 +14,16 @@ export {
   FRAME_PARAM,
   type PreviewToolbarProps,
 } from './ui/PreviewToolbar.tsx'
-export { useOnPage, useOnPageOptional } from './context.tsx'
+export { useOnPage, useOnPageApi, useOnPageOptional, useSessionSnapshot } from './context.tsx'
 export type {
   EditorRegistry,
   FieldEditorDef,
   FieldEditorProps,
   Links,
+  OnPageApi,
   OnPageContextValue,
+  OnPageState,
+  PanelKind,
   TargetIndex,
 } from './types.ts'
 export {
@@ -35,7 +38,7 @@ export {
   UploadEditor,
 } from './editors/index.ts'
 export { resolveEditor, mergeEditors } from './registry.ts'
-export { annotations, stega, composite, rowPrefixes } from './locators.ts'
+export { annotations, stega, composite } from './locators.ts'
 export {
   editable,
   editableOff,

package/src/layout.ts

@@ -71,8 +71,11 @@ export function useTrackElement(getElement: () => Element | null, fn: (el: Eleme
     run()
     const off = onLayoutChange(run)
     const el = getElement()
-    const ro = el ? new ResizeObserver(() => run()) : undefined
-    if (el) ro!.observe(el)
+    let ro: ResizeObserver | undefined
+    if (el) {
+      ro = new ResizeObserver(() => run())
+      ro.observe(el)
+    }
     return () => {
       off()
       ro?.disconnect()

package/src/locators.ts

@@ -8,7 +8,10 @@
  *   composite()    merge several; earlier locators win for the same element+path
  */
 import {
+  hasStegaMarker,
+  isTargetKind,
   parseRefKey,
+  rowPrefixes,
   targetKey,
   stegaDecode,
   type DocRef,
@@ -29,12 +32,14 @@ export function annotations(): Locator {
         if (!ref) return
         const label = el.getAttribute(ATTR.label) ?? undefined
         const field = el.getAttribute(ATTR.field)
+        const kind = el.getAttribute(ATTR.kind)
         if (field)
           out.push({
             el,
             ref,
             path: field,
-            kind: (el.getAttribute(ATTR.kind) as TargetKind) || 'field',
+            // Page markup is input: an unknown kind is treated as a plain field.
+            kind: isTargetKind(kind) ? kind : 'field',
             label,
             source: 'annotation',
           })
@@ -53,7 +58,7 @@ const SKIP_TAGS = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE', 'TEXTAREA'
 /** Lowest common ancestor of a set of elements. */
 function commonAncestor(els: Element[]): Element | null {
   if (!els.length) return null
-  let anc: Element | null = els[0]
+  let anc: Element | null = els[0] ?? null
   for (const el of els.slice(1)) {
     while (anc && !anc.contains(el)) anc = anc.parentElement
     if (!anc) return null
@@ -61,15 +66,6 @@ function commonAncestor(els: Element[]): Element | null {
   return anc
 }
 
-/** "layout.2.items.0.title" → ["layout.2", "layout.2.items.0"] (row paths, outermost first). */
-export function rowPrefixes(path: string): string[] {
-  const segs = path.split('.')
-  const out: string[] = []
-  for (let i = 1; i < segs.length; i++)
-    if (/^\d+$/.test(segs[i]) && i < segs.length - 1) out.push(segs.slice(0, i + 1).join('.'))
-  return out
-}
-
 export function stega(opts: { inferRows?: boolean } = {}): Locator {
   const inferRows = opts.inferRows ?? true
   return {
@@ -92,7 +88,7 @@ export function stega(opts: { inferRows?: boolean } = {}): Locator {
       const walker = doc.createTreeWalker(root, 4 /* NodeFilter.SHOW_TEXT */)
       for (let n = walker.nextNode(); n; n = walker.nextNode()) {
         const text = n.nodeValue
-        if (!text || !text.includes('\u2063\u2062')) continue
+        if (!text || !hasStegaMarker(text)) continue
         const parent = n.parentElement
         if (!parent || SKIP_TAGS.has(parent.tagName) || parent.closest(`[${UI}]`)) continue
         for (const m of stegaDecode(text)) {
@@ -121,8 +117,9 @@ export function stega(opts: { inferRows?: boolean } = {}): Locator {
         rich.set(k, [...(rich.get(k) ?? []), t])
       }
       for (const group of rich.values()) {
+        const [first] = group
         const el = commonAncestor(group.map((t) => t.el))
-        if (el) out.push({ ...group[0], el })
+        if (first && el) out.push({ ...first, el })
       }
 
       if (!inferRows) return out
@@ -170,7 +167,7 @@ export function stega(opts: { inferRows?: boolean } = {}): Locator {
         byList.set(k, entry)
       }
       for (const { ref, path, els } of byList.values()) {
-        const anc = els.length > 1 ? commonAncestor(els) : els[0].parentElement
+        const anc = els.length > 1 ? commonAncestor(els) : (els[0]?.parentElement ?? null)
         if (anc && anc !== root) rows.push({ el: anc, ref, path, kind: 'list', source: 'stega' })
       }
       return [...out, ...rows]

package/src/messages.ts

@@ -7,6 +7,7 @@ export const defaultMessages = {
   'dock.label': 'Page editor',
   'dock.loading': 'Loading editor…',
   'dock.unavailable': '{doc}: {error}',
+  'dock.saveFailed': '{doc}: {message}',
   'dock.nothing': 'Nothing editable on this page',
   'dock.conflict': '{doc}: changed by someone else',
   'dock.saving': 'Saving draft…',
@@ -45,6 +46,8 @@ export const defaultMessages = {
   'row.settings': 'Settings',
   'row.delete': 'Delete (undo with ⌘Z)',
   'row.addSection': 'Add section',
+  'row.addSectionAbove': 'Add section above',
+  'row.addSectionBelow': 'Add section below',
   'row.addFirstSection': 'Add a section',
   'row.addItem': 'Add {item}',
   'row.toolbar': '{label} actions',
@@ -57,6 +60,7 @@ export const defaultMessages = {
   'common.apply': 'Apply',
   'common.clear': 'Clear',
   'common.remove': 'Remove',
+  'common.removeItem': 'Remove {item}',
   'common.none': '—',
   'common.selected': '{count} selected',
   'search.placeholder': 'Search…',
@@ -82,6 +86,7 @@ export const defaultMessages = {
   'rt.italic': 'Italic',
   'rt.underline': 'Underline',
   'rt.link': 'Link',
+  'rt.linkApply': 'Apply',
   'rt.h2': 'Heading 2',
   'rt.h3': 'Heading 3',
   'rt.ul': 'Bulleted list',
@@ -94,15 +99,31 @@ export const defaultMessages = {
 
 export type MessageKey = keyof typeof defaultMessages
 export type Messages = Partial<Record<MessageKey, string>>
-/** Translate a message key (unknown keys are returned as-is, so plain text works too). */
-export type Translate = (
-  key: MessageKey | (string & {}),
-  vars?: Record<string, string | number>,
+
+/** The {placeholders} of a message: `Placeholders<'Saved {when}'>` is `'when'`. */
+export type Placeholders<S extends string> = S extends `${string}{${infer Name}}${infer Rest}`
+  ? Name | Placeholders<Rest>
+  : never
+
+/** The variables a message needs, by key. */
+export type MessageVars<K extends MessageKey> = Record<
+  Placeholders<(typeof defaultMessages)[K]>,
+  string | number
+>
+
+/**
+ * Translate a message key. A message with placeholders requires exactly those
+ * variables (`t('dock.saved', { ago })`); one without takes none. Unknown keys
+ * don't compile: show raw text without `t`.
+ */
+export type Translate = <K extends MessageKey>(
+  key: K,
+  ...vars: [Placeholders<(typeof defaultMessages)[K]>] extends [never] ? [] : [vars: MessageVars<K>]
 ) => string
 
 export function createTranslate(overrides: Messages = {}): Translate {
   const table: Record<string, string> = { ...defaultMessages, ...overrides }
-  return (key, vars) => {
+  return (key: string, vars?: Record<string, string | number>) => {
     const template = table[key] ?? key
     return vars
       ? template.replace(/\{(\w+)\}/g, (m, name: string) => (name in vars ? String(vars[name]) : m))