@payload-onpage/lexical 0.0.0-stage → 0.1.0

package/src/InlineRichText.tsx

@@ -0,0 +1,542 @@
+'use client'
+
+/**
+ * In-place rich-text editing with Lexical. The editable surface is laid over
+ * the rendered element, takes its classes (so the site's prose styles apply)
+ * and hides the original. Clicking outside, or "Done", commits; Escape cancels.
+ * Only a real change is written: the value is compared with what the same
+ * editor produced for the untouched content.
+ */
+import React, { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import { LexicalComposer } from '@lexical/react/LexicalComposer'
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext'
+import { RichTextPlugin } from '@lexical/react/LexicalRichTextPlugin'
+import { ContentEditable } from '@lexical/react/LexicalContentEditable'
+import { HistoryPlugin } from '@lexical/react/LexicalHistoryPlugin'
+import { ListPlugin } from '@lexical/react/LexicalListPlugin'
+import { LexicalErrorBoundary } from '@lexical/react/LexicalErrorBoundary'
+import {
+  $createHeadingNode,
+  $createQuoteNode,
+  $isHeadingNode,
+  $isQuoteNode,
+} from '@lexical/rich-text'
+import {
+  $isListNode,
+  INSERT_ORDERED_LIST_COMMAND,
+  INSERT_UNORDERED_LIST_COMMAND,
+  REMOVE_LIST_COMMAND,
+} from '@lexical/list'
+import { $setBlocksType } from '@lexical/selection'
+import { $findMatchingParent } from '@lexical/utils'
+import {
+  $createParagraphNode,
+  $createRangeSelectionFromDom,
+  $getNearestNodeFromDOMNode,
+  $getRoot,
+  $getSelection,
+  $isRangeSelection,
+  $isTextNode,
+  $setSelection,
+  FORMAT_TEXT_COMMAND,
+  type BaseSelection,
+  REDO_COMMAND,
+  UNDO_COMMAND,
+  type LexicalEditor,
+} from 'lexical'
+import { eachLexicalNode, newRowId, safeLinkUrl } from '@payload-onpage/core'
+import {
+  HIDDEN,
+  caretAt,
+  placeOver,
+  useEvent,
+  useTrackElement,
+  type FieldEditorProps,
+  type Translate,
+} from '@payload-onpage/react/editor-kit'
+import { $createPayloadLinkNode, $isPayloadLinkNode, type PayloadLinkNode } from './nodes.tsx'
+import { RICH_TEXT_NODES } from './nodeList.ts'
+import { fromEditorState, plainText, toEditorState, type RichTextState } from './convert.ts'
+
+export { RICH_TEXT_NODES }
+
+interface ToolbarState {
+  bold: boolean
+  italic: boolean
+  underline: boolean
+  block: string
+  link: boolean
+}
+
+function readToolbarState(): ToolbarState {
+  const sel = $getSelection()
+  if (!$isRangeSelection(sel))
+    return { bold: false, italic: false, underline: false, block: 'paragraph', link: false }
+  const anchor = sel.anchor.getNode()
+  const top = anchor.getKey() === 'root' ? anchor : anchor.getTopLevelElementOrThrow()
+  const list = $findMatchingParent(anchor, $isListNode)
+  const block = list
+    ? `list-${list.getListType()}`
+    : $isHeadingNode(top)
+      ? top.getTag()
+      : $isQuoteNode(top)
+        ? 'quote'
+        : 'paragraph'
+  return {
+    bold: sel.hasFormat('bold'),
+    italic: sel.hasFormat('italic'),
+    underline: sel.hasFormat('underline'),
+    block,
+    link: !!$findMatchingParent(anchor, $isPayloadLinkNode),
+  }
+}
+
+/**
+ * Pull the browser's current selection into Lexical. Keyboard-extended
+ * selections (⌥⇧→ and friends) don't always reach Lexical's model before a
+ * toolbar click, so every toolbar action syncs first and acts on what the user
+ * actually sees selected.
+ */
+function syncSelection(editor: LexicalEditor) {
+  const dom = window.getSelection()
+  const root = editor.getRootElement()
+  if (!dom || !root || !dom.anchorNode || !root.contains(dom.anchorNode)) return
+  editor.update(
+    () => {
+      const sel = $createRangeSelectionFromDom(dom, editor)
+      if (sel) $setSelection(sel)
+    },
+    { discrete: true },
+  )
+}
+
+/** The URL of the link around the selection, if any. */
+function currentLinkUrl(editor: LexicalEditor): string | undefined {
+  let url: string | undefined
+  editor.getEditorState().read(() => {
+    const sel = $getSelection()
+    if ($isRangeSelection(sel))
+      url = $findMatchingParent(sel.anchor.getNode(), $isPayloadLinkNode)?.getFields().url
+  })
+  return url
+}
+
+/** Link the selection to `url`; an empty url removes the link around it. */
+/** Link the selection; returns false (and changes nothing) for an unsafe URL such as `javascript:`. */
+function applyLink(editor: LexicalEditor, rawUrl: string, saved: BaseSelection | null): boolean {
+  const url = rawUrl.trim()
+  if (url && !safeLinkUrl(url)) return false
+  editor.update(() => {
+    // Focus moved to the URL field; put back the selection it was opened for.
+    if (saved) $setSelection(saved.clone())
+    const sel = $getSelection()
+    if (!$isRangeSelection(sel)) return
+    const nodes = sel.extract()
+    const existing = nodes.map((n) => $findMatchingParent(n, $isPayloadLinkNode)).find(Boolean) as
+      PayloadLinkNode | undefined
+    if (existing) {
+      if (!url) {
+        for (const child of existing.getChildren()) existing.insertBefore(child)
+        existing.remove()
+      } else {
+        existing.setFields({ ...existing.getFields(), url })
+      }
+      return
+    }
+    if (!url) return
+    let link: PayloadLinkNode | null = null
+    for (const node of nodes) {
+      if (!$isTextNode(node) || $findMatchingParent(node, $isPayloadLinkNode)) continue
+      if (!link || node.getPreviousSibling() !== link) {
+        // Payload's own link node carries an id; so do ours.
+        link = $createPayloadLinkNode(
+          { url, newTab: /^https?:/.test(url), linkType: 'custom' },
+          newRowId(),
+        )
+        node.insertBefore(link)
+      }
+      link.append(node)
+    }
+  })
+  return true
+}
+
+/** A toolbar button that keeps the editor's selection (and syncs a keyboard selection first). */
+function ToolButton({
+  label,
+  title,
+  pressed = false,
+  onAction,
+  id,
+}: {
+  label: React.ReactNode
+  title: string
+  pressed?: boolean
+  onAction: () => void
+  id: string
+}) {
+  const [editor] = useLexicalComposerContext()
+  return (
+    <button
+      type="button"
+      className="po-btn"
+      title={title}
+      aria-label={title}
+      aria-pressed={pressed}
+      data-testid={`onpage-rt-${id}`}
+      onMouseDown={(e) => e.preventDefault() /* keep the editor's selection */}
+      onClick={() => {
+        syncSelection(editor)
+        onAction()
+      }}
+    >
+      {label}
+    </button>
+  )
+}
+
+function Toolbar({ onDone, t }: { onDone: () => void; t: Translate }) {
+  const [editor] = useLexicalComposerContext()
+  const [state, setState] = useState<ToolbarState>({
+    bold: false,
+    italic: false,
+    underline: false,
+    block: 'paragraph',
+    link: false,
+  })
+  const [linkDraft, setLinkDraft] = useState<string | null>(null)
+  const savedSelection = useRef<BaseSelection | null>(null)
+  const [linkError, setLinkError] = useState(false)
+  const openLink = () => {
+    editor.getEditorState().read(() => {
+      savedSelection.current = $getSelection()?.clone() ?? null
+    })
+    setLinkDraft(currentLinkUrl(editor) ?? 'https://')
+  }
+  const saveLink = () => {
+    if (linkDraft === null) return
+    if (!applyLink(editor, linkDraft === 'https://' ? '' : linkDraft, savedSelection.current)) {
+      setLinkError(true)
+      return
+    }
+    setLinkError(false)
+    setLinkDraft(null)
+    editor.focus()
+  }
+  useEffect(
+    () =>
+      editor.registerUpdateListener(({ editorState }) =>
+        editorState.read(() => setState(readToolbarState())),
+      ),
+    [editor],
+  )
+
+  const setBlock = (kind: 'paragraph' | 'h2' | 'h3' | 'quote') =>
+    editor.update(() => {
+      const sel = $getSelection()
+      if (!$isRangeSelection(sel)) return
+      const target = state.block === kind ? 'paragraph' : kind
+      $setBlocksType(sel, () =>
+        target === 'paragraph'
+          ? $createParagraphNode()
+          : target === 'quote'
+            ? $createQuoteNode()
+            : $createHeadingNode(target),
+      )
+    })
+  const list = (type: 'bullet' | 'number') => {
+    if (state.block === `list-${type}`) editor.dispatchCommand(REMOVE_LIST_COMMAND, undefined)
+    else
+      editor.dispatchCommand(
+        type === 'bullet' ? INSERT_UNORDERED_LIST_COMMAND : INSERT_ORDERED_LIST_COMMAND,
+        undefined,
+      )
+  }
+  return (
+    <div className="po-rt-toolbar" role="toolbar" aria-label={t('rt.toolbar')}>
+      <ToolButton
+        label={<b>B</b>}
+        title={t('rt.bold')}
+        pressed={state.bold}
+        onAction={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, 'bold')}
+        id="bold"
+      />
+      <ToolButton
+        label={<i>I</i>}
+        title={t('rt.italic')}
+        pressed={state.italic}
+        onAction={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, 'italic')}
+        id="italic"
+      />
+      <ToolButton
+        label={<u>U</u>}
+        title={t('rt.underline')}
+        pressed={state.underline}
+        onAction={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, 'underline')}
+        id="underline"
+      />
+      <ToolButton
+        label="🔗"
+        title={t('rt.link')}
+        pressed={state.link}
+        onAction={openLink}
+        id="link"
+      />
+      <ToolButton
+        label="H2"
+        title={t('rt.h2')}
+        pressed={state.block === 'h2'}
+        onAction={() => setBlock('h2')}
+        id="h2"
+      />
+      <ToolButton
+        label="H3"
+        title={t('rt.h3')}
+        pressed={state.block === 'h3'}
+        onAction={() => setBlock('h3')}
+        id="h3"
+      />
+      <ToolButton
+        label="•"
+        title={t('rt.ul')}
+        pressed={state.block === 'list-bullet'}
+        onAction={() => list('bullet')}
+        id="ul"
+      />
+      <ToolButton
+        label="1."
+        title={t('rt.ol')}
+        pressed={state.block === 'list-number'}
+        onAction={() => list('number')}
+        id="ol"
+      />
+      <ToolButton
+        label="❝"
+        title={t('rt.quote')}
+        pressed={state.block === 'quote'}
+        onAction={() => setBlock('quote')}
+        id="quote"
+      />
+      <ToolButton
+        label="↶"
+        title={t('dock.undo')}
+        onAction={() => editor.dispatchCommand(UNDO_COMMAND, undefined)}
+        id="undo"
+      />
+      <ToolButton
+        label="↷"
+        title={t('dock.redo')}
+        onAction={() => editor.dispatchCommand(REDO_COMMAND, undefined)}
+        id="redo"
+      />
+      <ToolButton label={t('rt.done')} title={t('rt.done')} onAction={onDone} id="done" />
+      {linkDraft !== null && (
+        <span style={{ display: 'inline-flex', gap: 4, marginLeft: 6 }}>
+          <input
+            className="po-input"
+            style={{ width: 260, height: 28 }}
+            value={linkDraft}
+            aria-invalid={linkError || undefined}
+            title={linkError ? t('rt.linkInvalid') : undefined}
+            ref={(el) => el?.focus()}
+            placeholder={t('rt.linkPlaceholder')}
+            onChange={(e) => setLinkDraft(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter') {
+                e.preventDefault()
+                saveLink()
+              } else if (e.key === 'Escape') {
+                e.preventDefault()
+                e.stopPropagation()
+                setLinkDraft(null)
+              }
+            }}
+            data-testid="onpage-rt-link-input"
+          />
+          <button
+            type="button"
+            className="po-btn"
+            onMouseDown={(e) => e.preventDefault()}
+            onClick={saveLink}
+            data-testid="onpage-rt-link-apply"
+          >
+            Apply
+          </button>
+        </span>
+      )}
+    </div>
+  )
+}
+
+/**
+ * Grabs the editor instance and puts the caret where the user clicked —
+ * through Lexical's own selection (setting only the DOM selection leaves
+ * Lexical's model at the end of the text, so keys and toolbar act there).
+ */
+function Bridge({
+  onReady,
+  point,
+}: {
+  onReady: (editor: LexicalEditor) => void
+  point?: { x: number; y: number }
+}) {
+  const [editor] = useLexicalComposerContext()
+  useEffect(() => {
+    onReady(editor)
+    const root = editor.getRootElement()
+    if (!root) return
+    // Wait two frames so the surface sits exactly over the original text.
+    let raf = requestAnimationFrame(
+      () =>
+        (raf = requestAnimationFrame(() => {
+          const hit = point ? caretAt(point, root) : null
+          // Focus first: Lexical may restore its own selection on focus, which would
+          // undo the caret placement if it came before.
+          root.focus({ preventScroll: true })
+          editor.update(
+            () => {
+              const node = hit ? $getNearestNodeFromDOMNode(hit.node) : null
+              if (node && $isTextNode(node)) node.select(hit!.offset, hit!.offset)
+              else $getRoot().selectEnd()
+            },
+            { discrete: true },
+          )
+        })),
+    )
+    return () => cancelAnimationFrame(raf)
+  }, [editor, onReady, point])
+  return null
+}
+
+export function InlineRichText({
+  field,
+  value,
+  element,
+  commit,
+  close,
+  ghost,
+  live,
+  point,
+  t,
+}: FieldEditorProps) {
+  const box = useRef<HTMLDivElement>(null)
+  const editorRef = useRef<LexicalEditor | null>(null)
+  const baseline = useRef<string | null>(null)
+  const done = useRef(false)
+  // The surface takes the element's classes, so the site's prose styles apply.
+  const [className] = useState(() => {
+    const cls = element()?.className
+    return typeof cls === 'string' ? cls : ''
+  })
+  const onReady = useCallback((editor: LexicalEditor) => {
+    editorRef.current = editor
+    baseline.current = JSON.stringify(editor.getEditorState().toJSON())
+  }, [])
+  const initialState = useMemo(() => JSON.stringify(toEditorState(value)), []) // eslint-disable-line react-hooks/exhaustive-deps
+
+  useLayoutEffect(() => {
+    const el = element()
+    if (el) {
+      // Position before first paint, so the caret hit-test finds the surface.
+      if (box.current) placeOver(box.current, el)
+      el.setAttribute(HIDDEN, 'true')
+    }
+    return () => element()?.removeAttribute(HIDDEN)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  // Follow the original element's box as the page scrolls and reflows.
+  useTrackElement(element, (el) => {
+    if (!box.current) return
+    if (!el.hasAttribute(HIDDEN)) el.setAttribute(HIDDEN, 'true')
+    placeOver(box.current, el)
+  })
+
+  const finish = (save: boolean) => {
+    if (done.current) return
+    done.current = true
+    const editor = editorRef.current
+    if (save && editor) {
+      const json = editor.getEditorState().toJSON() as unknown as RichTextState
+      if (JSON.stringify(json) !== baseline.current) {
+        const next = fromEditorState(json)
+        commit(plainText(next) || hasOpaque(next) ? next : null)
+        const surface = editor.getRootElement()
+        if (!live && surface) ghost({ html: surface.innerHTML, className })
+      }
+    }
+    close()
+  }
+
+  // Commit when the user clicks anywhere outside the editor.
+  // Escape (inside the editor) cancels.
+  const onOutside = useEvent((e: PointerEvent) => {
+    if (box.current && !box.current.contains(e.target as Node)) finish(true)
+  })
+  const onEscape = useEvent((e: KeyboardEvent) => {
+    if (e.key === 'Escape' && box.current?.contains(document.activeElement)) {
+      e.preventDefault()
+      finish(false)
+    }
+  })
+  useEffect(() => {
+    const onDown = (e: PointerEvent) => onOutside(e)
+    const onKey = (e: KeyboardEvent) => onEscape(e)
+    document.addEventListener('pointerdown', onDown, true)
+    document.addEventListener('keydown', onKey)
+    return () => {
+      document.removeEventListener('pointerdown', onDown, true)
+      document.removeEventListener('keydown', onKey)
+    }
+  }, [onEscape, onOutside])
+
+  return (
+    <div
+      ref={box}
+      className="po-rt"
+      role="group"
+      aria-label={t('inline.label', { field: field.label })}
+      data-testid="onpage-inline-richtext"
+    >
+      <LexicalComposer
+        initialConfig={{
+          namespace: 'payload-onpage',
+          nodes: RICH_TEXT_NODES,
+          editorState: initialState,
+          onError: (error) => console.error('[payload-onpage] rich text', error),
+          theme: { text: { bold: 'po-b', italic: 'po-i', underline: 'po-u' } },
+        }}
+      >
+        <Toolbar onDone={() => finish(true)} t={t} />
+        <RichTextPlugin
+          contentEditable={
+            <ContentEditable
+              className={`${className} po-rt-surface`}
+              aria-label={t('inline.label', { field: field.label })}
+            />
+          }
+          ErrorBoundary={LexicalErrorBoundary}
+        />
+        <HistoryPlugin />
+        <ListPlugin />
+        <Bridge onReady={onReady} point={point} />
+      </LexicalComposer>
+    </div>
+  )
+}
+
+/** Does the value hold nodes the editor shows as placeholders (uploads, blocks…)? Then it isn't empty. */
+function hasOpaque(state: RichTextState): boolean {
+  let found = false
+  eachLexicalNode(state, (n) => {
+    if (
+      n.type !== 'root' &&
+      n.type !== 'paragraph' &&
+      n.type !== 'text' &&
+      n.type !== 'linebreak' &&
+      !n.children
+    )
+      found = true
+  })
+  return found
+}

package/src/constants.ts

@@ -0,0 +1,2 @@
+/** Node type the inline editor uses for Payload nodes it keeps as-is (uploads, blocks…). */
+export const OPAQUE_TYPE = 'onpage-opaque'

package/src/convert.ts

@@ -0,0 +1,73 @@
+/**
+ * Payload rich text ⇄ the inline editor's Lexical state. Node types we edit go
+ * through as-is; everything else is wrapped in an OpaqueNode on the way in and
+ * unwrapped on the way out, byte-for-byte.
+ */
+import { eachLexicalNode, type LexicalNode, type LexicalState } from '@payload-onpage/core'
+import { OPAQUE_TYPE } from './constants.ts'
+
+export const EDITABLE_NODE_TYPES = new Set([
+  'root',
+  'paragraph',
+  'heading',
+  'quote',
+  'list',
+  'listitem',
+  'text',
+  'linebreak',
+  'tab',
+  'link',
+])
+
+type Node = LexicalNode
+export type RichTextState = LexicalState
+
+export const EMPTY_STATE: RichTextState = {
+  root: {
+    type: 'root',
+    version: 1,
+    format: '',
+    indent: 0,
+    direction: null,
+    children: [
+      { type: 'paragraph', version: 1, format: '', indent: 0, direction: null, children: [] },
+    ],
+  },
+}
+
+function wrap(node: Node): Node {
+  if (!EDITABLE_NODE_TYPES.has(node.type)) return { type: OPAQUE_TYPE, version: 1, data: node }
+  return Array.isArray(node.children) ? { ...node, children: node.children.map(wrap) } : node
+}
+
+function unwrap(node: Node): Node {
+  if (node.type === OPAQUE_TYPE) return node.data as Node
+  return Array.isArray(node.children) ? { ...node, children: node.children.map(unwrap) } : node
+}
+
+export function isRichTextState(value: unknown): value is RichTextState {
+  return (
+    !!value && typeof value === 'object' && (value as Partial<RichTextState>).root?.type === 'root'
+  )
+}
+
+export function toEditorState(value: unknown): RichTextState {
+  const state = isRichTextState(value) ? value : EMPTY_STATE
+  const root = wrap(state.root)
+  // Lexical needs at least one block child to place a caret.
+  if (!root.children?.length) root.children = EMPTY_STATE.root.children
+  return { root }
+}
+
+export function fromEditorState(state: RichTextState): RichTextState {
+  return { root: unwrap(state.root) }
+}
+
+/** Plain text of a state (used to treat a blank editor as "no value"). */
+export function plainText(state: RichTextState): string {
+  const parts: string[] = []
+  eachLexicalNode(state, (n) => {
+    if (typeof n.text === 'string') parts.push(n.text)
+  })
+  return parts.join('').trim()
+}

package/src/editor.ts

@@ -0,0 +1,10 @@
+/** The rich-text editor component and its Lexical nodes (statically imported; prefer `lexicalEditors` for lazy loading). */
+export { InlineRichText, RICH_TEXT_NODES } from './InlineRichText.tsx'
+export {
+  PayloadLinkNode,
+  OpaqueNode,
+  $createPayloadLinkNode,
+  $isPayloadLinkNode,
+  describeNode,
+  type OpaqueData,
+} from './nodes.tsx'

package/src/index.ts

@@ -0,0 +1,33 @@
+'use client'
+
+/**
+ * @payload-onpage/lexical — inline rich-text editing for Payload's Lexical
+ * richText fields.
+ *
+ *   <OnPageEditor editors={lexicalEditors} … />   // the Next adapter includes it by default
+ *
+ * Light by design: the Lexical editor itself (~75 KB gz with Lexical) loads
+ * only when someone opens a rich-text field. It reads and writes Payload's
+ * Lexical JSON; links keep Payload's shape, and nodes it doesn't edit
+ * (uploads, blocks, relationships…) are kept as-is and shown as placeholders.
+ * The editor component and its nodes are in `@payload-onpage/lexical/editor`.
+ */
+import type { EditorRegistry } from '@payload-onpage/react/editor-kit'
+import { lazy } from 'react'
+
+const InlineRichText = lazy(() =>
+  import('./InlineRichText.tsx').then((m) => ({ default: m.InlineRichText })),
+)
+
+export const lexicalEditors: EditorRegistry = {
+  richText: { mode: 'inline', component: InlineRichText },
+}
+
+export {
+  toEditorState,
+  fromEditorState,
+  plainText,
+  isRichTextState,
+  type RichTextState,
+} from './convert.ts'
+export { OPAQUE_TYPE } from './constants.ts'

package/src/nodeList.ts

@@ -0,0 +1,13 @@
+/** The node classes the inline editor registers (no React UI imported here). */
+import { HeadingNode, QuoteNode } from '@lexical/rich-text'
+import { ListItemNode, ListNode } from '@lexical/list'
+import { OpaqueNode, PayloadLinkNode } from './nodes.tsx'
+
+export const RICH_TEXT_NODES = [
+  HeadingNode,
+  QuoteNode,
+  ListNode,
+  ListItemNode,
+  PayloadLinkNode,
+  OpaqueNode,
+]