@payload-onpage/react 0.0.0-stage → 0.1.0

package/src/styles.ts

@@ -0,0 +1,122 @@
+/**
+ * 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.
+ */
+export const PO_Z = 2147483000
+
+export const PO_CSS = `
+.po-layer{position:fixed;inset:0;pointer-events:none;z-index:${PO_Z};font:13px/1.35 system-ui,-apple-system,"Segoe UI",sans-serif;color:#0f172a}
+.po-layer *{box-sizing:border-box}
+.po-outline{position:fixed;border:2px solid #4f7cff;border-radius:4px;pointer-events:none;transition:all .06s ease-out}
+.po-outline.is-block{border-style:dashed;border-color:#4f7cff99}
+.po-outline.is-item{border-color:#22a06b}
+.po-chip{position:fixed;transform:translateY(-100%);background:#3b63e0;color:#fff;font-size:11px;font-weight:600;padding:2px 6px;border-radius:4px 4px 0 0;white-space:nowrap;pointer-events:none}
+.po-chip.is-item{background:#167a45}
+.po-bar{position:fixed;display:flex;gap:2px;padding:3px;background:#0f172a;border-radius:8px;box-shadow:0 6px 24px #0f172a40;pointer-events:auto}
+.po-bar.is-item{background:#14532d}
+.po-btn{all:unset;display:inline-flex;align-items:center;justify-content:center;gap:6px;min-width:28px;height:28px;padding:0 8px;border-radius:6px;color:#fff;font:600 12px/1 system-ui,-apple-system,sans-serif;cursor:pointer;white-space:nowrap}
+.po-btn:hover{background:#ffffff1f}
+.po-btn:focus-visible{outline:2px solid #93c5fd;outline-offset:1px}
+.po-btn[disabled]{opacity:.35;cursor:default;background:none}
+.po-btn.is-danger:hover{background:#ef444455}
+.po-add{position:fixed;transform:translate(-50%,-50%);pointer-events:auto}
+.po-add .po-btn{background:#3b63e0;box-shadow:0 2px 10px #4f7cff66;height:24px;font-size:11px}
+.po-add .po-btn:hover{background:#2f5bd9}
+.po-add.is-item .po-btn{background:#167a45;box-shadow:0 2px 10px #167a4555}
+.po-panel{position:fixed;width:320px;max-height:min(70vh,560px);overflow:auto;background:#fff;color:#0f172a;border-radius:12px;box-shadow:0 20px 60px #0f172a40,0 0 0 1px #0f172a14;pointer-events:auto;padding:14px}
+.po-panel .po-h3{margin:0 0 10px;font:700 13px/1.2 system-ui,sans-serif}
+.po-panel .po-h4{margin:14px 0 6px;font:600 11px/1.2 system-ui,sans-serif;text-transform:uppercase;letter-spacing:.06em;color:#64748b}
+.po-row{display:flex;flex-direction:column;gap:4px;margin:0 0 10px}
+.po-row label{font-weight:600;font-size:12px}
+.po-row small{color:#64748b;font-size:11px}
+.po-input,.po-select{all:unset;box-sizing:border-box;width:100%;height:32px;padding:0 10px;border:1px solid #cbd5e1;border-radius:8px;background:#fff;font:13px system-ui,sans-serif;color:#0f172a}
+.po-select{appearance:auto;-webkit-appearance:auto}
+.po-input:focus,.po-select:focus{border-color:#4f7cff;box-shadow:0 0 0 3px #4f7cff33}
+.po-check{display:flex;align-items:center;gap:8px;font-size:12px;font-weight:600}
+.po-seg{display:flex;flex-wrap:wrap;gap:4px}
+.po-seg button{all:unset;padding:5px 9px;border:1px solid #cbd5e1;border-radius:7px;font:12px system-ui,sans-serif;cursor:pointer;background:#fff}
+.po-seg button[aria-pressed="true"]{background:#0f172a;color:#fff;border-color:#0f172a}
+.po-modal-bg{position:fixed;inset:0;background:#0f172a66;pointer-events:auto;display:flex;align-items:center;justify-content:center;padding:24px}
+.po-modal{width:min(880px,100%);max-height:85vh;display:flex;flex-direction:column;background:#fff;border-radius:14px;box-shadow:0 30px 80px #0f172a55;overflow:hidden}
+.po-modal header{display:flex;align-items:center;gap:10px;padding:14px 16px;border-bottom:1px solid #e2e8f0}
+.po-modal header .po-h3{margin:0;flex:1;font:700 14px system-ui,sans-serif}
+.po-modal .po-body{padding:14px 16px;overflow:auto}
+.po-modal .po-btn{color:#0f172a}
+.po-modal .po-btn:hover{background:#f1f5f9}
+.po-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(150px,1fr));gap:10px}
+.po-tile{all:unset;display:flex;flex-direction:column;gap:6px;cursor:pointer;border-radius:10px;padding:6px;border:2px solid transparent}
+.po-tile:hover,.po-tile:focus-visible{border-color:#4f7cff;background:#f8fafc}
+.po-tile img{width:100%;aspect-ratio:4/3;object-fit:cover;border-radius:6px;background:#f1f5f9}
+.po-tile span{font-size:11px;color:#475569;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.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 .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-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}
+.po-rt{position:absolute;pointer-events:auto}
+.po-rt-surface{outline:2px solid #4f7cff;outline-offset:6px;border-radius:2px;min-height:1.5em}
+.po-rt-surface:focus{outline:2px solid #4f7cff}
+.po-rt-toolbar{position:absolute;left:0;top:-48px;display:flex;gap:2px;padding:3px;background:#0f172a;border-radius:8px;box-shadow:0 6px 24px #0f172a40}
+.po-rt-toolbar .po-btn[aria-pressed="true"]{background:#ffffff2e}
+.po-pop{position:fixed;min-width:220px;max-width:340px;background:#fff;color:#0f172a;border-radius:10px;box-shadow:0 14px 40px #0f172a40,0 0 0 1px #0f172a14;pointer-events:auto;padding:10px}
+.po-pop .po-row{margin-bottom:8px}
+.po-pop-list{display:flex;flex-direction:column;gap:2px;max-height:260px;overflow:auto}
+.po-pop-list button{all:unset;padding:7px 9px;border-radius:7px;cursor:pointer;font:13px system-ui,sans-serif}
+.po-pop-list button:hover,.po-pop-list button:focus-visible,.po-pop-list button[aria-selected="true"]{background:#eef2ff}
+.po-ghost{position:absolute;pointer-events:none;white-space:pre-wrap;word-break:break-word}
+.po-docs{font-size:11px;padding:2px 7px;border-radius:999px;background:#ffffff1f}
+.po-frame-bg{position:fixed;inset:0;background:#0f172acc;pointer-events:auto;display:flex;flex-direction:column;align-items:center;padding:56px 16px 16px}
+.po-frame-bg iframe{background:#fff;border:0;border-radius:12px;box-shadow:0 30px 80px #0008;height:100%;max-width:100%}
+.po-badge{padding:2px 8px;border-radius:999px;background:#f59e0b;color:#111;font-weight:700;font-size:11px;text-transform:uppercase;letter-spacing:.04em}
+.po-b{font-weight:700}.po-i{font-style:italic}.po-u{text-decoration:underline}
+.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 .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}
+
+.po-dialog-head{display:flex;align-items:center;gap:8px;margin:0 0 10px}
+.po-modal .po-dialog-head{margin:0;padding:14px 16px;border-bottom:1px solid #e2e8f0}
+.po-dialog-head .po-h3{flex:1;margin:0;font:700 14px/1.2 system-ui,sans-serif}
+.po-close{color:#0f172a;min-width:24px;height:24px}
+.po-close:hover{background:#f1f5f9}
+.po-bar-label{cursor:default;opacity:.8}
+.po-muted{color:#64748b;margin:6px 0}
+.po-error{color:#b91c1c;margin:6px 0}
+.po-center{text-align:center;margin-top:12px}
+.po-actions{display:flex;gap:6px}
+.po-inline-row{flex-direction:row;align-items:center}
+.po-search{width:240px}
+.po-picker{cursor:pointer;display:flex;align-items:center}
+.po-group{border:0;margin:0;padding:0}
+.po-primary,.po-pop .po-primary,.po-panel .po-primary{background:#3b63e0;color:#fff}
+.po-primary:hover{background:#2f5bd9}
+.po-pop .po-btn,.po-panel .po-btn{color:#0f172a}
+.po-pop .po-btn.po-primary,.po-panel .po-btn.po-primary{color:#fff}
+.po-frame-close{all:unset;position:absolute;inset:0;cursor:pointer}
+.po-frame-bg iframe{position:relative}
+.po-input[aria-invalid="true"]{border-color:#dc2626}
+html[data-onpage-editing] [data-onpage-focusable]:focus-visible{outline:2px solid #4f7cff;outline-offset:2px}
+@media (prefers-reduced-motion:reduce){.po-outline{transition:none}}
+`
+
+let injected = false
+export function injectStyles() {
+  if (injected || typeof document === 'undefined') return
+  injected = true
+  const el = document.createElement('style')
+  el.setAttribute('data-onpage-styles', '')
+  el.textContent = PO_CSS
+  document.head.appendChild(el)
+}

package/src/targets.ts

@@ -0,0 +1,101 @@
+'use client'
+
+/**
+ * Keeps an index of the page's targets current: scans with the locator on
+ * mount and again whenever the page's DOM changes (a server refresh, a client
+ * re-render, lazy content), ignoring the editor's own UI. Rescans are
+ * debounced and run when the browser is idle.
+ */
+import { targetKey, type Locator, type Target, type TargetKind } from '@payload-onpage/core'
+import { useEffect, useState } from 'react'
+import { ATTR } from './annotations.ts'
+import { isOurs } from './dom.ts'
+import type { TargetIndex } from './types.ts'
+
+const FIELD_KINDS = new Set<TargetKind>(['text', 'textarea', 'richtext', 'media', 'field'])
+export const isFieldTarget = (t: Target): boolean => FIELD_KINDS.has(t.kind)
+export const isRowTarget = (t: Target): boolean => t.kind === 'item'
+
+export function buildIndex(all: Target[]): TargetIndex {
+  const byEl = new Map<Element, Target[]>()
+  const byPath = new Map<string, Target[]>()
+  // Annotations first: they are precise, inferred targets are a fallback.
+  const sorted = [...all].sort(
+    (a, b) => Number(a.source !== 'annotation') - Number(b.source !== 'annotation'),
+  )
+  for (const t of sorted) {
+    byEl.set(t.el, [...(byEl.get(t.el) ?? []), t])
+    const k = targetKey(t.ref, t.path)
+    byPath.set(k, [...(byPath.get(k) ?? []), t])
+  }
+  return {
+    all: sorted,
+    at: (el) => byEl.get(el) ?? [],
+    find: (key, path, kinds) =>
+      (byPath.get(targetKey(key, path)) ?? []).find(
+        (t) => t.el.isConnected && (!kinds || kinds.includes(t.kind)),
+      ),
+  }
+}
+
+/** The innermost field target and all row targets (innermost first) at or above `el`. */
+export function targetsAt(
+  index: TargetIndex,
+  el: Element | null,
+): { field?: Target; rows: Target[] } {
+  let field: Target | undefined
+  const rows: Target[] = []
+  for (let node = el; node; node = node.parentElement) {
+    for (const t of index.at(node)) {
+      if (!field && isFieldTarget(t)) field = t
+      if (isRowTarget(t)) rows.push(t)
+    }
+  }
+  return { field, rows }
+}
+
+const WATCHED = [ATTR.ref, ATTR.field, ATTR.row, ATTR.list, 'alt']
+const idle = (fn: () => void): (() => void) => {
+  if (typeof requestIdleCallback === 'function') {
+    const h = requestIdleCallback(fn, { timeout: 300 })
+    return () => cancelIdleCallback(h)
+  }
+  const h = setTimeout(fn, 50)
+  return () => clearTimeout(h)
+}
+
+export function useTargets(locator: Locator, root: () => ParentNode | null): TargetIndex {
+  const [index, setIndex] = useState<TargetIndex>(() => buildIndex([]))
+  useEffect(() => {
+    const r = root()
+    if (!r) return
+    let debounce: ReturnType<typeof setTimeout> | undefined
+    let cancelIdle: (() => void) | undefined
+    const scan = () => setIndex(buildIndex(locator.scan(r)))
+    scan()
+    const observer = new MutationObserver((records) => {
+      if (
+        records.every((m) =>
+          isOurs(m.target instanceof Element ? m.target : m.target.parentElement),
+        )
+      )
+        return
+      clearTimeout(debounce)
+      cancelIdle?.()
+      debounce = setTimeout(() => (cancelIdle = idle(scan)), 120)
+    })
+    observer.observe(r, {
+      subtree: true,
+      childList: true,
+      characterData: true,
+      attributes: true,
+      attributeFilter: WATCHED,
+    })
+    return () => {
+      observer.disconnect()
+      clearTimeout(debounce)
+      cancelIdle?.()
+    }
+  }, [locator, root])
+  return index
+}

package/src/types.ts

@@ -0,0 +1,132 @@
+/** Public types of the editor UI. */
+import type { ComponentType } from 'react'
+import type {
+  DocRef,
+  EditorSession,
+  MediaLibrary,
+  Renderer,
+  SchemaField,
+  SessionSnapshot,
+  Target,
+  TargetKind,
+} from '@payload-onpage/core'
+import type { MessageKey, Translate } from './messages.ts'
+
+export interface EditingState {
+  /** refKey of the document */
+  key: string
+  path: string
+  /** Editor id from the registry ("text", "richText", …). */
+  editor: string
+  point?: { x: number; y: number }
+  /** The element that was clicked (several elements may show one field). */
+  el?: Element
+}
+
+export type Panel =
+  | { kind: 'settings'; key: string; path: string; title: string }
+  | { kind: 'blocks'; key: string; listPath: string; index: number }
+  | null
+
+export interface Selection {
+  key: string
+  path: string
+}
+
+/** Props every field editor receives. */
+export interface FieldEditorProps {
+  docKey: string
+  path: string
+  field: SchemaField
+  /** The element showing the field (re-resolved after each refresh). */
+  element: () => Element | null
+  value: unknown
+  /** Commit a value (one undo step, autosaved). */
+  commit: (value: unknown) => void
+  /** Live preview while editing (no history entry, not saved). */
+  preview: (value: unknown) => void
+  /** 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
+  /** True when the page renders this document from editor state (instant); false = server refresh. */
+  live: boolean
+  point?: { x: number; y: number }
+  /** UI strings. */
+  t: Translate
+}
+
+/**
+ * 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.
+ */
+export interface FieldEditorDef {
+  mode: 'inline' | 'popover'
+  component: ComponentType<FieldEditorProps>
+}
+
+export type EditorRegistry = Record<string, FieldEditorDef>
+
+/** Navigation targets. `exit` and `mode` are endpoints the editor POSTs to. */
+export interface Links {
+  exit: string
+  admin?: (ref: DocRef) => string
+  mode?: (mode: 'edit' | 'view') => string
+}
+
+export interface TargetIndex {
+  all: Target[]
+  /** Targets whose element is exactly `el`. */
+  at: (el: Element) => Target[]
+  find: (key: string, path: string, kinds?: TargetKind[]) => Target | undefined
+}
+
+/** What extensions and field editors can use from the editor (`useOnPage()`). */
+export interface OnPageContextValue {
+  session: EditorSession
+  snap: SessionSnapshot
+  renderer: Renderer
+  media?: MediaLibrary
+  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
+  /** 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
+  /** Open the right editor for a field (registry resolution); false if none applies. */
+  edit: (
+    key: string,
+    path: string,
+    opts?: { point?: { x: number; y: number }; kind?: TargetKind; anchor?: Element },
+  ) => 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
+}

package/src/ui/BlockPicker.tsx

@@ -0,0 +1,49 @@
+'use client'
+
+import { fieldAtPath, insertItem, newBlockRow, updateArray } from '@payload-onpage/core'
+import { useOnPage } from '../context.tsx'
+import { Dialog } from './Dialog.tsx'
+
+/** Choose a block type to insert at a position in a blocks field. */
+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
+  const { key, listPath, index } = panel
+  const field = fieldAtPath(state.schema.fields, state.doc, listPath)?.field
+  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))),
+    )
+    setPanel(null)
+    setSelected({ key, path: `${listPath}.${index}` })
+  }
+
+  return (
+    <Dialog
+      title={t('blocks.title')}
+      onClose={() => setPanel(null)}
+      t={t}
+      width={640}
+      testId="onpage-block-picker"
+    >
+      <div className="po-blocks">
+        {blocks.map((b) => (
+          <button
+            key={b.slug}
+            type="button"
+            onClick={() => choose(b.slug)}
+            data-testid={`onpage-block-${b.slug}`}
+          >
+            {b.labels.singular}
+          </button>
+        ))}
+      </div>
+    </Dialog>
+  )
+}

package/src/ui/Dialog.tsx

@@ -0,0 +1,159 @@
+'use client'
+
+/**
+ * The one dialog primitive: labelled, focus moves in on open and back on
+ * close, Tab stays inside (modal), Escape closes. `variant="popover"` is
+ * anchored next to an element and closes on an outside click.
+ */
+import { useEffect, useId, useRef, useState, type CSSProperties, type ReactNode } from 'react'
+import { focusableIn, popoverPosition } from '../dom.ts'
+import { useLayoutTick } from '../layout.ts'
+import type { Translate } from '../messages.ts'
+
+export interface DialogProps {
+  title: string
+  onClose: () => void
+  children: ReactNode
+  t: Translate
+  /** modal: centered with a backdrop. panel: fixed side panel. popover: next to `anchor`. */
+  variant?: 'modal' | 'panel' | 'popover'
+  anchor?: () => Element | null
+  width?: number
+  testId?: string
+  /** Extra header content (search box, actions). */
+  actions?: ReactNode
+}
+
+export function Dialog({
+  title,
+  onClose,
+  children,
+  t,
+  variant = 'modal',
+  anchor,
+  width,
+  testId,
+  actions,
+}: DialogProps) {
+  const box = useRef<HTMLDivElement>(null)
+  const titleId = useId()
+  const [height, setHeight] = useState(240)
+  useLayoutTick() // popovers follow their anchor
+
+  // Focus in on open, back on close.
+  useEffect(() => {
+    const previous = document.activeElement as HTMLElement | null
+    const el = box.current
+    if (el)
+      (
+        el.querySelector<HTMLElement>('[autofocus],[data-autofocus]') ??
+        focusableIn(el)[0] ??
+        el
+      ).focus({ preventScroll: true })
+    return () => previous?.focus?.({ preventScroll: true })
+  }, [])
+
+  // Popovers flip above their anchor when there's no room below: track their height.
+  useEffect(() => {
+    const el = box.current
+    if (variant !== 'popover' || !el) return
+    const ro = new ResizeObserver(() => setHeight(el.offsetHeight))
+    ro.observe(el)
+    return () => ro.disconnect()
+  }, [variant])
+
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.stopPropagation()
+        onClose()
+        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]
+      if (e.shiftKey && document.activeElement === first) {
+        e.preventDefault()
+        last.focus()
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault()
+        first.focus()
+      }
+    }
+    const onDown = (e: PointerEvent) => {
+      if (variant === 'popover' && box.current && !box.current.contains(e.target as Node)) onClose()
+    }
+    document.addEventListener('keydown', onKey, true)
+    // Deferred, so the click that opened a popover doesn't close it.
+    const timer = setTimeout(() => document.addEventListener('pointerdown', onDown, true))
+    return () => {
+      clearTimeout(timer)
+      document.removeEventListener('keydown', onKey, true)
+      document.removeEventListener('pointerdown', onDown, true)
+    }
+  }, [onClose, variant])
+
+  const header = (
+    <header className="po-dialog-head">
+      <h2 className="po-h3" id={titleId}>
+        {title}
+      </h2>
+      {actions}
+      <button
+        type="button"
+        className="po-btn po-close"
+        onClick={onClose}
+        aria-label={t('common.close')}
+      >
+        ✕
+      </button>
+    </header>
+  )
+
+  if (variant === 'modal') {
+    return (
+      // Backdrop: a press outside the dialog closes it (Escape works from the keyboard).
+      <div
+        className="po-modal-bg"
+        onPointerDown={(e) => e.target === e.currentTarget && onClose()}
+        data-testid={testId}
+      >
+        <div
+          ref={box}
+          className="po-modal"
+          role="dialog"
+          aria-modal="true"
+          aria-labelledby={titleId}
+          tabIndex={-1}
+          style={width ? { width: `min(${width}px, 100%)` } : undefined}
+        >
+          {header}
+          <div className="po-body">{children}</div>
+        </div>
+      </div>
+    )
+  }
+  const style: CSSProperties =
+    variant === 'popover'
+      ? {
+          ...popoverPosition(anchor?.() ?? null, { width: width ?? 300, height }),
+          width: width ?? 300,
+        }
+      : { top: 72, right: 16 }
+  return (
+    <div
+      ref={box}
+      className={variant === 'popover' ? 'po-pop' : 'po-panel'}
+      role="dialog"
+      aria-labelledby={titleId}
+      tabIndex={-1}
+      style={style}
+      data-testid={testId}
+    >
+      {header}
+      {children}
+    </div>
+  )
+}