@payload-onpage/react 0.2.1 → 0.3.1

package/src/ui/Overlay.tsx

@@ -6,35 +6,34 @@
  * from the target elements whenever the layout changes.
  */
 import {
-  cloneRow,
   fieldAtPath,
   getAt,
-  insertItem,
   isEditablePath,
-  moveItem,
+  isListField,
   newArrayRow,
   refKey,
-  removeItem,
   resolveRow,
-  updateArray,
-  type Doc,
+  rowPrefixes,
   type RowInfo,
   type Target,
+  isReady,
+  type RefKey,
 } from '@payload-onpage/core'
 import { useEffect, useState } from 'react'
 import { useOnPage } from '../context.tsx'
 import { isOurs } from '../dom.ts'
+import { belowList, GEOMETRY, inViewport, outlineBox, toolbarPosition } from '../geometry.ts'
 import { useLayoutTick } from '../layout.ts'
+import { ToolbarButton } from './ToolbarButton.tsx'
 import { targetsAt } from '../targets.ts'
-import { hasSettings } from './SettingsPanel.tsx'
+import { insertRow, rowOps } from '../rowOps.ts'
+import { hasSettings } from '../settings.ts'
 
 interface Hover {
-  field?: Target
+  field?: Target | undefined
   rows: Target[] // innermost first
 }
 
-const VIEW_PAD = 8
-
 function useHover(): Hover {
   const { targets } = useOnPage()
   const [hover, setHover] = useState<Hover>({ rows: [] })
@@ -70,14 +69,14 @@ function Outline({
   if (r.width === 0 && r.height === 0) return null
   return (
     <>
-      <div
-        className={`po-outline${variant ? ` is-${variant}` : ''}`}
-        style={{ top: r.top - 2, left: r.left - 2, width: r.width + 4, height: r.height + 4 }}
-      />
+      <div className={`po-outline${variant ? ` is-${variant}` : ''}`} style={outlineBox(r)} />
       {label && (
         <div
           className={`po-chip${variant === 'item' ? ' is-item' : ''}`}
-          style={{ top: Math.max(r.top - 2, 22), left: r.left - 2 }}
+          style={{
+            top: Math.max(r.top - GEOMETRY.outline, GEOMETRY.chipMinTop),
+            left: r.left - GEOMETRY.outline,
+          }}
         >
           {label}
         </div>
@@ -87,7 +86,7 @@ function Outline({
 }
 
 interface ActiveRow {
-  key: string
+  key: RefKey
   info: RowInfo
   el: Element
 }
@@ -96,94 +95,67 @@ function RowToolbar({ row, variant }: { row: ActiveRow; variant: 'block' | 'item
   const { session, setSelected, setPanel, selected, targets, t } = useOnPage()
   const { key, info, el } = row
   const r = el.getBoundingClientRect()
-  if (r.bottom < 40 || r.top > window.innerHeight - 40) return null
-  const top = Math.min(Math.max(r.top + VIEW_PAD, 60), r.bottom - 40)
-  const right = Math.max(window.innerWidth - r.right + VIEW_PAD, VIEW_PAD)
-  const { listPath, index, length, rowFields, path } = info
+  if (!inViewport(r, GEOMETRY.toolbar)) return null
+  const { path } = info
   const label = targets.find(key, path, ['item'])?.label || info.label
-  const apply = (fn: (d: Doc) => Doc) => session.apply(key, fn)
-  const max = info.listField.maxRows
-  const min = info.listField.minRows ?? 0
-
+  const ops = rowOps(session, key, info)
   const move = (dir: -1 | 1) => {
-    apply((d) => updateArray(d, listPath, (a) => moveItem(a, index, index + dir)))
-    setSelected({ key, path: `${listPath}.${index + dir}` })
+    const next = ops.move(dir)
+    if (next) setSelected(next)
   }
   const duplicate = () => {
-    apply((d) =>
-      updateArray(d, listPath, (a) => insertItem(a, index + 1, cloneRow(a[index], rowFields))),
-    )
-    setSelected({ key, path: `${listPath}.${index + 1}` })
+    const next = ops.duplicate()
+    if (next) setSelected(next)
   }
   const remove = () => {
-    apply((d) => updateArray(d, listPath, (a) => removeItem(a, index)))
-    if (selected?.key === key && selected.path.startsWith(path)) setSelected(null)
+    if (ops.remove() && selected?.key === key && selected.path.startsWith(path)) setSelected(null)
   }
   return (
     <div
       className={`po-bar${variant === 'item' ? ' is-item' : ''}`}
-      style={{ top, right }}
+      style={toolbarPosition(r)}
       role="toolbar"
       aria-label={t('row.toolbar', { label })}
       data-testid={`onpage-${variant}-toolbar`}
     >
       <span className="po-btn po-bar-label">{label}</span>
-      <button
-        type="button"
-        className="po-btn"
-        disabled={index === 0}
+      <ToolbarButton
+        label={t('row.moveUp')}
+        icon="↑"
+        disabled={!ops.canMove(-1)}
         onClick={() => move(-1)}
-        aria-label={t('row.moveUp')}
-        title={t('row.moveUp')}
-        data-testid={`onpage-${variant}-up`}
-      >
-        ↑
-      </button>
-      <button
-        type="button"
-        className="po-btn"
-        disabled={index >= length - 1}
+        testId={`onpage-${variant}-up`}
+      />
+      <ToolbarButton
+        label={t('row.moveDown')}
+        icon="↓"
+        disabled={!ops.canMove(1)}
         onClick={() => move(1)}
-        aria-label={t('row.moveDown')}
-        title={t('row.moveDown')}
-        data-testid={`onpage-${variant}-down`}
-      >
-        ↓
-      </button>
-      <button
-        type="button"
-        className="po-btn"
-        disabled={max !== undefined && length >= max}
+        testId={`onpage-${variant}-down`}
+      />
+      <ToolbarButton
+        label={t('row.duplicate')}
+        icon="⧉"
+        disabled={!ops.canDuplicate}
         onClick={duplicate}
-        aria-label={t('row.duplicate')}
-        title={t('row.duplicate')}
-        data-testid={`onpage-${variant}-duplicate`}
-      >
-        ⧉
-      </button>
-      {hasSettings(rowFields, path, key, targets) && (
-        <button
-          type="button"
-          className="po-btn"
+        testId={`onpage-${variant}-duplicate`}
+      />
+      {hasSettings(info.rowFields, path, key, targets) && (
+        <ToolbarButton
+          label={t('row.settings')}
+          icon="⚙"
           onClick={() => setPanel({ kind: 'settings', key, path, title: label })}
-          aria-label={t('row.settings')}
-          title={t('row.settings')}
-          data-testid={`onpage-${variant}-settings`}
-        >
-          ⚙
-        </button>
+          testId={`onpage-${variant}-settings`}
+        />
       )}
-      <button
-        type="button"
-        className="po-btn is-danger"
-        disabled={length <= min}
+      <ToolbarButton
+        label={t('row.delete')}
+        icon="✕"
+        danger
+        disabled={!ops.canRemove}
         onClick={remove}
-        aria-label={t('row.delete')}
-        title={t('row.delete')}
-        data-testid={`onpage-${variant}-delete`}
-      >
-        ✕
-      </button>
+        testId={`onpage-${variant}-delete`}
+      />
     </div>
   )
 }
@@ -201,7 +173,7 @@ function InsertPoints({ row }: { row: ActiveRow }) {
           onClick={() =>
             setPanel({ kind: 'blocks', key: row.key, listPath: row.info.listPath, index })
           }
-          aria-label={`${t('row.addSection')} (${edge})`}
+          aria-label={t(edge === 'above' ? 'row.addSectionAbove' : 'row.addSectionBelow')}
           data-testid={`onpage-insert-${edge}`}
         >
           + {t('row.addSection')}
@@ -220,10 +192,11 @@ function AddItem({ list }: { list: Target }) {
   const { snap, session, setPanel, setSelected, t } = useOnPage()
   const key = refKey(list.ref)
   const state = snap.docs[key]
-  if (!state?.schema || !state.doc || !isEditablePath(state.schema, list.path)) return null
+  if (!isReady(state) || !isEditablePath(state.schema, list.path)) return null
   const field = fieldAtPath(state.schema.fields, state.doc, list.path)?.field
-  if (!field || (field.type !== 'array' && field.type !== 'blocks')) return null
-  const length = (getAt<unknown[]>(state.doc, list.path) ?? []).length
+  if (!field || !isListField(field)) return null
+  const rows = getAt(state.doc, list.path)
+  const length = Array.isArray(rows) ? rows.length : 0
   const r = list.el.getBoundingClientRect()
   if (field.type === 'blocks') {
     // Sections get "+ Add section" above/below each one; this covers an empty list.
@@ -231,7 +204,10 @@ function AddItem({ list }: { list: Target }) {
     return (
       <div
         className="po-add"
-        style={{ top: r.top + Math.min(r.height / 2, 160), left: r.left + r.width / 2 }}
+        style={{
+          top: r.top + Math.min(r.height / 2, GEOMETRY.emptyListOffset),
+          left: r.left + r.width / 2,
+        }}
       >
         <button
           type="button"
@@ -246,13 +222,10 @@ function AddItem({ list }: { list: Target }) {
   }
   if (field.maxRows !== undefined && length >= field.maxRows) return null
   // Below the list, or pinned to the bottom of the viewport while the list runs past it.
-  if (r.bottom < 0 || r.top > window.innerHeight - 40) return null
-  const y = Math.min(r.bottom + 14, window.innerHeight - 84)
+  if (!inViewport(r) || r.top > window.innerHeight - GEOMETRY.toolbar) return null
+  const y = belowList(r)
   const item = list.label || field.labels?.singular || field.label
-  const add = () => {
-    session.apply(key, (d) => updateArray(d, list.path, (a) => [...a, newArrayRow(field)]))
-    setSelected({ key, path: `${list.path}.${length}` })
-  }
+  const add = () => setSelected(insertRow(session, key, list.path, length, newArrayRow(field)))
   return (
     <div className="po-add is-item" style={{ top: y, left: r.left + r.width / 2 }}>
       <button type="button" className="po-btn" onClick={add} data-testid="onpage-add-item">
@@ -271,8 +244,7 @@ export function Overlay() {
     if (!target) return null
     const key = refKey(target.ref)
     const state = snap.docs[key]
-    const info =
-      state?.schema && state.doc ? resolveRow(state.schema, state.doc, target.path) : null
+    const info = isReady(state) ? resolveRow(state.schema, state.doc, target.path) : null
     return info ? { key, info, el: target.el } : null
   }
 
@@ -284,13 +256,13 @@ export function Overlay() {
   // Its section: the outermost enclosing row of a blocks field (may be itself).
   let section: ActiveRow | null = null
   if (active) {
-    const segs = active.info.path.split('.')
-    for (let i = 1; i < segs.length && !section; i++) {
-      if (!/^\d+$/.test(segs[i])) continue
-      const path = segs.slice(0, i + 1).join('.')
+    for (const path of [...rowPrefixes(active.info.path), active.info.path]) {
       const candidate =
         path === active.info.path ? active : rowFor(targets.find(active.key, path, ['item']))
-      if (candidate?.info.isBlock) section = candidate
+      if (candidate?.info.isBlock) {
+        section = candidate
+        break
+      }
     }
   }
   const item = active && section?.info.path !== active.info.path ? active : null
@@ -302,7 +274,8 @@ export function Overlay() {
     : undefined
   const emptyLists = lists.filter((l) => {
     const doc = snap.docs[refKey(l.ref)]?.doc
-    return doc && !(getAt<unknown[]>(doc, l.path) ?? []).length
+    const rows = doc ? getAt(doc, l.path) : undefined
+    return doc && !(Array.isArray(rows) && rows.length)
   })
   const hoverField = !editing ? hover.field : undefined
 

package/src/ui/PreviewToolbar.tsx

@@ -5,21 +5,21 @@
  * page in a framed viewport. Signed-in editors can switch back to editing;
  * people on a shared link can leave to the published page.
  */
-import { useEffect, useMemo, useState, useSyncExternalStore } from 'react'
+import { useEffect, useMemo, useState } from 'react'
+import { useEditorStyles, useIsClient } from '../useIsClient.ts'
 import { createPortal } from 'react-dom'
 import { UI } from '../dom.ts'
 import { createTranslate, type Messages } from '../messages.ts'
-import { injectStyles } from '../styles.ts'
 import { PostButton } from './PostButton.tsx'
 
 export interface PreviewToolbarProps {
   /** Endpoint that leaves preview (POST), back to the published page. */
   exitHref: string
   /** Endpoint that switches to editing (POST); omit for people who can't edit (shared links). */
-  editHref?: string
+  editHref?: string | undefined
   /** Opened from a shared preview link. */
-  shared?: boolean
-  messages?: Messages
+  shared?: boolean | undefined
+  messages?: Messages | undefined
 }
 
 const DEVICES = [
@@ -34,19 +34,11 @@ export const inPreviewFrame = (): boolean =>
   typeof window !== 'undefined' &&
   (window.self !== window.top || new URLSearchParams(window.location.search).has(FRAME_PARAM))
 
-const noop = () => () => {}
-const useMounted = () =>
-  useSyncExternalStore(
-    noop,
-    () => true,
-    () => false,
-  )
-
 export function PreviewToolbar({ exitHref, editHref, shared, messages }: PreviewToolbarProps) {
   const [device, setDevice] = useState<(typeof DEVICES)[number] | null>(null)
-  const mounted = useMounted()
+  const mounted = useIsClient()
   const t = useMemo(() => createTranslate(messages), [messages])
-  useEffect(() => injectStyles(), [])
+  useEditorStyles()
   useEffect(() => {
     if (!device) return
     const onKey = (e: KeyboardEvent) => e.key === 'Escape' && setDevice(null)

package/src/ui/SettingsPanel.tsx

@@ -6,40 +6,29 @@
  * spacing…), checkboxes, numbers, dates, relationships, URLs and other plain
  * text, images that aren't on the page. Changes apply immediately.
  */
-import { fieldAtPath, getAt, relationTitle, toText, type SchemaField } from '@payload-onpage/core'
+import {
+  fieldAtPath,
+  getAt,
+  relationTitle,
+  rowFieldsOf,
+  toText,
+  isListField,
+  type ChoiceField,
+  type NumberField,
+  type ScalarField,
+  type SchemaField,
+  isReady,
+  type RefKey,
+} from '@payload-onpage/core'
 import { useId, useRef, useState, type KeyboardEvent, type RefObject } from 'react'
 import { useOnPage } from '../context.tsx'
 import type { Translate } from '../messages.ts'
-import type { TargetIndex } from '../types.ts'
+import { checkedOf } from '../editors/CheckboxEditor.tsx'
+import { selectedValues } from '../editors/SelectEditor.tsx'
+import { canEdit } from '../registry.ts'
+import { settable } from '../settings.ts'
 import { Dialog } from './Dialog.tsx'
 
-const SKIP = new Set(['id', 'blockType', 'blockName'])
-const TEXTUAL = new Set(['text', 'textarea', 'email', 'number', 'date', 'relationship', 'upload'])
-const INPUT_TYPES = new Set(['text', 'textarea', 'email', 'number'])
-
-function settable(field: SchemaField, path: string, key: string, 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 TEXTUAL.has(field.type) && !targets.find(key, full)
-  }
-}
-
-export const hasSettings = (
-  fields: SchemaField[],
-  path: string,
-  key: string,
-  targets: TargetIndex,
-): boolean => fields.some((f) => settable(f, path, key, targets))
-
 const display = (v: unknown, t: Translate): string => {
   if (v == null || v === '') return t('common.none')
   if (Array.isArray(v))
@@ -53,9 +42,9 @@ function TextInput({
   field,
   id,
 }: {
-  docKey: string
+  docKey: RefKey
   path: string
-  field: SchemaField
+  field: ScalarField | NumberField
   id: string
 }) {
   const { session, snap } = useOnPage()
@@ -92,14 +81,15 @@ function Segmented({
   field,
   labelId,
 }: {
-  docKey: string
+  docKey: RefKey
   path: string
-  field: SchemaField
+  field: ChoiceField
   labelId: string
 }) {
   const { session, snap } = useOnPage()
-  const options = field.options ?? []
-  const current = getAt(snap.docs[docKey]?.doc, path) ?? field.defaultValue ?? ''
+  const options = field.options
+  const current =
+    selectedValues(getAt(snap.docs[docKey]?.doc, path) ?? field.defaultValue, field)[0] ?? ''
   const index = Math.max(
     0,
     options.findIndex((o) => o.value === current),
@@ -148,54 +138,17 @@ function Control({
   id,
   labelId,
 }: {
-  docKey: string
+  docKey: RefKey
   path: string
   field: SchemaField
   anchor: RefObject<HTMLDivElement | null>
   id: string
   labelId: string
 }) {
-  const { session, snap, edit, t } = useOnPage()
+  const { session, snap, edit, editors, t } = useOnPage()
   const value = getAt(snap.docs[docKey]?.doc, path)
   const set = (v: unknown) => session.setValue(docKey, path, v)
-  if ((field.type === 'select' || field.type === 'radio') && !field.hasMany) {
-    const options = field.options ?? []
-    if (options.length <= 5)
-      return <Segmented docKey={docKey} path={path} field={field} labelId={labelId} />
-    return (
-      <select
-        id={id}
-        className="po-select"
-        value={toText(value ?? field.defaultValue)}
-        onChange={(e) => set(e.target.value || null)}
-        data-testid={`onpage-setting-${path}`}
-      >
-        {!field.required && <option value="">{t('common.none')}</option>}
-        {options.map((o) => (
-          <option key={o.value} value={o.value}>
-            {o.label}
-          </option>
-        ))}
-      </select>
-    )
-  }
-  if (field.type === 'checkbox') {
-    return (
-      <label className="po-check">
-        <input
-          type="checkbox"
-          checked={Boolean(value ?? field.defaultValue)}
-          onChange={(e) => set(e.target.checked)}
-          data-testid={`onpage-setting-${path}`}
-        />
-        {field.label}
-      </label>
-    )
-  }
-  if (INPUT_TYPES.has(field.type))
-    return <TextInput docKey={docKey} path={path} field={field} id={id} />
-  // Everything else opens its field editor, anchored to the panel row.
-  return (
+  const openEditor = (
     <button
       id={id}
       type="button"
@@ -208,9 +161,59 @@ function Control({
         : display(value, t)}
     </button>
   )
+  // A field with its own editor (e.g. `editor: 'color'`) opens it, whatever its type.
+  if (field.editor && canEdit(editors[field.editor], field)) return openEditor
+  switch (field.type) {
+    case 'select':
+    case 'radio': {
+      if (field.hasMany) return openEditor
+      if (field.options.length <= 5)
+        return <Segmented docKey={docKey} path={path} field={field} labelId={labelId} />
+      return (
+        <select
+          id={id}
+          className="po-select"
+          value={selectedValues(value ?? field.defaultValue, field)[0] ?? ''}
+          onChange={(e) => set(e.target.value || null)}
+          data-testid={`onpage-setting-${path}`}
+        >
+          {!field.required && <option value="">{t('common.none')}</option>}
+          {field.options.map((o) => (
+            <option key={o.value} value={o.value}>
+              {o.label}
+            </option>
+          ))}
+        </select>
+      )
+    }
+    case 'checkbox':
+      return (
+        <label className="po-check">
+          <input
+            type="checkbox"
+            checked={checkedOf(value, field)}
+            onChange={(e) => set(e.target.checked)}
+            data-testid={`onpage-setting-${path}`}
+          />
+          {field.label}
+        </label>
+      )
+    case 'text':
+    case 'textarea':
+    case 'email':
+    case 'number':
+      return 'hasMany' in field && field.hasMany ? (
+        openEditor
+      ) : (
+        <TextInput docKey={docKey} path={path} field={field} id={id} />
+      )
+    default:
+      // Dates, relationships, images…: open the field editor, anchored to the panel row.
+      return openEditor
+  }
 }
 
-function Row({ docKey, path, field }: { docKey: string; path: string; field: SchemaField }) {
+function Row({ docKey, path, field }: { docKey: RefKey; path: string; field: SchemaField }) {
   const anchor = useRef<HTMLDivElement>(null)
   const id = useId()
   const labelId = `${id}-label`
@@ -234,7 +237,7 @@ function Row({ docKey, path, field }: { docKey: string; path: string; field: Sch
   )
 }
 
-function Fields({ docKey, fields, path }: { docKey: string; fields: SchemaField[]; path: string }) {
+function Fields({ docKey, fields, path }: { docKey: RefKey; fields: SchemaField[]; path: string }) {
   const { targets } = useOnPage()
   return (
     <>
@@ -246,7 +249,7 @@ function Fields({ docKey, fields, path }: { docKey: string; fields: SchemaField[
             return (
               <fieldset key={f.name} className="po-group">
                 <legend className="po-h4">{f.label}</legend>
-                <Fields docKey={docKey} fields={f.fields ?? []} path={full} />
+                <Fields docKey={docKey} fields={f.fields} path={full} />
               </fieldset>
             )
           }
@@ -260,11 +263,11 @@ export function SettingsPanel() {
   const { panel, setPanel, snap, t } = useOnPage()
   if (panel?.kind !== 'settings') return null
   const state = snap.docs[panel.key]
-  if (!state?.schema || !state.doc) return null
-  const owner = fieldAtPath(state.schema.fields, state.doc, panel.path)
+  if (!isReady(state)) return null
+  const owner = fieldAtPath(state.schema.fields, state.doc, panel.path)?.field
   // Row fields: the block's fields for a blocks row, the item fields for an array row.
   const fields =
-    owner?.field.type === 'blocks' ? (owner.block?.fields ?? []) : (owner?.field.fields ?? [])
+    owner && isListField(owner) ? (rowFieldsOf(owner, getAt(state.doc, panel.path)) ?? []) : []
   return (
     <Dialog
       variant="panel"

package/src/ui/ToolbarButton.tsx

@@ -0,0 +1,36 @@
+'use client'
+
+import type { ReactNode } from 'react'
+
+/** An icon button in a toolbar: labelled for assistive tech, with the label (or a hint) as its tooltip. */
+export function ToolbarButton({
+  label,
+  hint,
+  icon,
+  onClick,
+  disabled,
+  danger,
+  testId,
+}: {
+  label: string
+  hint?: string
+  icon: ReactNode
+  onClick: () => void
+  disabled?: boolean
+  danger?: boolean
+  testId: string
+}) {
+  return (
+    <button
+      type="button"
+      className={`po-btn${danger ? ' is-danger' : ''}`}
+      disabled={disabled}
+      onClick={onClick}
+      aria-label={label}
+      title={hint ?? label}
+      data-testid={testId}
+    >
+      {icon}
+    </button>
+  )
+}

package/src/useEvent.ts

@@ -7,10 +7,12 @@ import { useCallback, useInsertionEffect, useRef } from 'react'
  * pattern). Our own, because the React bundled with Next.js 15 doesn't export
  * `useEffectEvent`. Call it from effects and event handlers, not during render.
  */
-export function useEvent<A extends unknown[], R>(fn: (...args: A) => R): (...args: A) => R {
+export function useEvent<F extends (...args: never[]) => unknown>(fn: F): F {
   const latest = useRef(fn)
   useInsertionEffect(() => {
     latest.current = fn
   })
-  return useCallback((...args: A) => latest.current(...args), [])
+  const stable = useCallback((...args: Parameters<F>) => latest.current(...args), [])
+  // The wrapper has F's exact signature: it forwards its arguments and result unchanged.
+  return stable as F
 }

package/src/useIsClient.ts

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