@estiva-app/ui 0.66.0 → 0.68.0

package/src/ReferenceMenu.test.tsx

@@ -0,0 +1,289 @@
+// @vitest-environment jsdom
+/**
+ * A chip's menu while writing (Miky, 14 Oct): a click on a chip opens Open and
+ * its card instead of following it; a chip just pasted opens the menu by
+ * itself, without taking the caret, and typing on closes it with no card.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { Editor } from '@tiptap/core'
+import { NodeSelection, TextSelection } from '@tiptap/pm/state'
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { BlockId, ReferenceNode, type ReferenceViewProps } from './BlockNodes'
+import { LinkChips } from './LinkChips'
+import { ReferenceCards } from './ReferenceCards'
+import { ReferenceMenu, ReferenceMenuView, isReferenceMenuOpen, referenceMenuClick } from './ReferenceMenu'
+
+const URL_ = 'https://app.example/i/one'
+const V = 'nostr:naddr1example'
+
+type Json = { type: string; text?: string; attrs?: Record<string, unknown>; content?: Json[] }
+const inline = (ed: Editor) => (ed.getJSON() as Json).content?.[0].content ?? []
+const chipOf = (ed: Editor) => inline(ed).find((n) => n.type === 'reference')
+const para = (...content: unknown[]): Record<string, unknown> => ({ type: 'doc', content: [{ type: 'paragraph', attrs: { blockId: 'p1' }, content }] })
+const tick = () => new Promise((resolve) => setTimeout(resolve, 0))
+// jsdom has no ClipboardEvent; `pasteText` takes the paste's event, so a plain one stands in.
+const paste = (ed: Editor, text: string) => ed.view.pasteText(text, new Event('paste') as ClipboardEvent)
+const press = (ed: Editor, key: string) => {
+  const event = new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true })
+  ed.view.dom.dispatchEvent(event)
+  return event.defaultPrevented
+}
+
+let editor: Editor | undefined
+afterEach(() => {
+  cleanup()
+  editor?.destroy()
+  editor = undefined
+})
+
+/** An editor with the menu, and a stand-in app that knows `known` and answers `ask` when told to. */
+const make = (content: Record<string, unknown>, known: Map<string, string>, answers: (() => void)[] = []) => {
+  editor = new Editor({
+    extensions: [
+      StarterKit.configure({ link: false }),
+      BlockId,
+      ReferenceNode,
+      ReferenceCards,
+      ReferenceMenu,
+      LinkChips.configure({
+        referenceOf: (url) => known.get(url),
+        ask: (urls) =>
+          new Promise<void>((resolve) =>
+            answers.push(() => {
+              for (const url of urls) known.set(url, V)
+              resolve()
+            }),
+          ),
+      }),
+    ],
+    content,
+  })
+  return editor
+}
+
+/** The caret at the end of the first paragraph. */
+const toEnd = (ed: Editor) => ed.view.dispatch(ed.state.tr.setSelection(TextSelection.create(ed.state.doc, ed.state.doc.content.size - 1)))
+
+describe('ReferenceMenu', () => {
+  it('opens by itself on a pasted URL that becomes its chip, and typing on closes it with no card', async () => {
+    const ed = make(para({ type: 'text', text: 'See ' }), new Map([[URL_, V]]))
+    await tick()
+    toEnd(ed)
+    paste(ed, URL_)
+    expect(chipOf(ed)?.attrs).toMatchObject({ uri: V, href: URL_ })
+    expect(isReferenceMenuOpen(ed.state)).toBe(true)
+    // The caret stayed in the text, after the chip.
+    expect(ed.state.selection.empty).toBe(true)
+    ed.view.dispatch(ed.state.tr.insertText(' and more'))
+    expect(isReferenceMenuOpen(ed.state)).toBe(false)
+    expect(chipOf(ed)?.attrs?.embed).toBeNull()
+  })
+
+  it('opens when a pasted URL\'s answer comes back with the caret still after it, not once the person typed on', async () => {
+    const answers: (() => void)[] = []
+    const ed = make(para({ type: 'text', text: 'See ' }), new Map(), answers)
+    await tick()
+    toEnd(ed)
+    paste(ed, URL_)
+    // Asked at once: a pasted URL is whole.
+    expect(answers).toHaveLength(1)
+    answers[0]()
+    await tick()
+    expect(chipOf(ed)?.attrs).toMatchObject({ uri: V })
+    expect(isReferenceMenuOpen(ed.state)).toBe(true)
+
+    const later: (() => void)[] = []
+    const other = 'https://app.example/i/two'
+    const ed2 = make(para({ type: 'text', text: 'See ' }), new Map(), later)
+    await tick()
+    toEnd(ed2)
+    paste(ed2, other)
+    ed2.view.dispatch(ed2.state.tr.insertText(' then'))
+    later[0]()
+    await tick()
+    expect(chipOf(ed2)?.attrs).toMatchObject({ uri: V })
+    expect(isReferenceMenuOpen(ed2.state)).toBe(false)
+  })
+
+  it('stays open while a URL elsewhere becomes its chip, and closes when the editor loses focus', async () => {
+    const answers: (() => void)[] = []
+    const other = 'https://app.example/i/two'
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'paragraph', attrs: { blockId: 'p1' }, content: [{ type: 'text', text: 'See ' }, { type: 'reference', attrs: { uri: V } }] },
+        { type: 'paragraph', attrs: { blockId: 'p2' }, content: [{ type: 'text', text: other }] },
+      ],
+    }
+    const ed = make(doc, new Map(), answers)
+    await tick()
+    expect(referenceMenuClick(ed, 5)).toBe(true)
+    answers[0]()
+    await tick()
+    expect((ed.getJSON() as Json).content?.[1].content?.[0].type).toBe('reference')
+    expect(isReferenceMenuOpen(ed.state)).toBe(true)
+    ed.view.dom.dispatchEvent(new FocusEvent('blur'))
+    expect(isReferenceMenuOpen(ed.state)).toBe(false)
+  })
+
+  it('opens on a chip pasted right before an identical one', () => {
+    const ed = make(para({ type: 'text', text: 'a ' }, { type: 'reference', attrs: { uri: V } }), new Map())
+    ed.view.dispatch(ed.state.tr.setSelection(TextSelection.create(ed.state.doc, 3)))
+    ed.view.dispatch(ed.state.tr.insert(3, ed.schema.nodes.reference.create({ uri: V })).setMeta('uiEvent', 'paste'))
+    expect(ed.state.selection.from).toBe(4)
+    expect(isReferenceMenuOpen(ed.state)).toBe(true)
+  })
+
+  it('leaves a key with a modifier to the editor', async () => {
+    const ed = make(para({ type: 'text', text: 'See ' }), new Map([[URL_, V]]))
+    await tick()
+    toEnd(ed)
+    paste(ed, URL_)
+    const shifted = new KeyboardEvent('keydown', { key: 'ArrowDown', shiftKey: true, bubbles: true, cancelable: true })
+    ed.view.dom.dispatchEvent(shifted)
+    expect(shifted.defaultPrevented).toBe(false)
+  })
+
+  it('offers no Open for a chip with nothing to open', () => {
+    // No view: the chip draws no control of its own, and it has no URL.
+    const ed = make(para({ type: 'text', text: 'See ' }, { type: 'reference', attrs: { uri: V } }), new Map())
+    render(<ReferenceMenuView editor={ed} />)
+    act(() => void referenceMenuClick(ed, 5))
+    expect(screen.queryByRole('menuitem', { name: 'Open' })).toBeNull()
+    expect(screen.getByRole('menuitemradio', { name: 'Compact' })).toBeDefined()
+  })
+
+  it('forgets a paste edited inside: each keystroke in it is not an ask', async () => {
+    const answers: (() => void)[] = []
+    const ed = make(para({ type: 'text', text: 'See ' }), new Map(), answers)
+    await tick()
+    toEnd(ed)
+    paste(ed, URL_)
+    expect(answers).toHaveLength(1)
+    // A character fixed in the middle of the pasted URL, the caret left there.
+    const at = 5 + URL_.length - 3
+    ed.view.dispatch(ed.state.tr.setSelection(TextSelection.create(ed.state.doc, at)))
+    for (const ch of 'xyz') ed.view.dispatch(ed.state.tr.insertText(ch))
+    toEnd(ed)
+    for (const ch of 'abc') ed.view.dispatch(ed.state.tr.insertText(ch))
+    expect(answers).toHaveLength(1)
+  })
+
+  it('opens on a chip picked from a list, which puts a space after it', async () => {
+    const ed = make(para({ type: 'text', text: 'See ' }), new Map())
+    toEnd(ed)
+    ed.commands.insertContent([{ type: 'reference', attrs: { uri: V } }, { type: 'text', text: ' ' }])
+    expect(isReferenceMenuOpen(ed.state)).toBe(true)
+  })
+
+  it('does not open on a URL typed by hand, an undo, or a document loaded over the editor', async () => {
+    const ed = make(para({ type: 'text', text: 'See ' }), new Map([[URL_, V]]))
+    await tick()
+    toEnd(ed)
+    for (const ch of URL_) ed.view.dispatch(ed.state.tr.insertText(ch))
+    ed.view.dispatch(ed.state.tr.insertText(' '))
+    expect(chipOf(ed)?.attrs).toMatchObject({ uri: V })
+    expect(isReferenceMenuOpen(ed.state)).toBe(false)
+    ed.commands.setContent(para({ type: 'text', text: 'x ' }, { type: 'reference', attrs: { uri: V } }))
+    expect(isReferenceMenuOpen(ed.state)).toBe(false)
+  })
+
+  it('keeps Enter for a new line after a paste until an arrow highlights a row; then Enter chooses it', async () => {
+    const ed = make(para({ type: 'text', text: 'See ' }), new Map([[URL_, V]]))
+    await tick()
+    toEnd(ed)
+    paste(ed, URL_)
+    expect(isReferenceMenuOpen(ed.state)).toBe(true)
+    // ↓ to Open, ↓ to None, ↓ to Compact, ↓ to Detailed.
+    for (let i = 0; i < 4; i++) expect(press(ed, 'ArrowDown')).toBe(true)
+    expect(press(ed, 'Enter')).toBe(true)
+    expect(chipOf(ed)?.attrs?.embed).toBe('detailed')
+    expect(isReferenceMenuOpen(ed.state)).toBe(false)
+    // Closed, Enter is the editor's again.
+    expect((ed.getJSON() as Json).content).toHaveLength(1)
+  })
+
+  it('opens from the keyboard with Enter on a selected chip, and Escape closes it', () => {
+    const ed = make(para({ type: 'text', text: 'See ' }, { type: 'reference', attrs: { uri: V, embed: 'compact' } }), new Map())
+    ed.view.dispatch(ed.state.tr.setSelection(NodeSelection.create(ed.state.doc, 5)))
+    expect(press(ed, 'Enter')).toBe(true)
+    expect(isReferenceMenuOpen(ed.state)).toBe(true)
+    // The chip is still there: Enter did not replace it with a line break.
+    expect(chipOf(ed)).toBeDefined()
+    // Open is highlighted; ↑ wraps to Detailed.
+    press(ed, 'ArrowUp')
+    expect(press(ed, 'Escape')).toBe(true)
+    expect(isReferenceMenuOpen(ed.state)).toBe(false)
+    expect(chipOf(ed)?.attrs?.embed).toBe('compact')
+  })
+
+  it('opens on a click only while editing', () => {
+    const ed = make(para({ type: 'text', text: 'See ' }, { type: 'reference', attrs: { uri: V } }), new Map())
+    ed.setEditable(false)
+    expect(referenceMenuClick(ed, 5)).toBe(false)
+    ed.setEditable(true)
+    expect(referenceMenuClick(ed, 5)).toBe(true)
+    expect(isReferenceMenuOpen(ed.state)).toBe(true)
+    // The caret right after the chip, not the chip selected: no selection toolbar beside the menu, and typing does not replace it.
+    expect(ed.state.selection.empty && ed.state.selection.from).toBe(6)
+  })
+})
+
+describe('ReferenceMenuView', () => {
+  function Linked({ uri }: ReferenceViewProps) {
+    return (
+      <a href={`/o/${uri}`} onClick={(event) => (followed(uri), event.preventDefault())}>
+        Item
+      </a>
+    )
+  }
+  const followed = vi.fn()
+
+  function Harness({ content }: { content: Record<string, unknown> }) {
+    const e = useEditor({
+      extensions: [StarterKit.configure({ link: false }), BlockId, ReferenceNode.configure({ view: Linked }), ReferenceCards, ReferenceMenu],
+      content,
+    })
+    editor = e ?? undefined
+    return (
+      <>
+        <EditorContent editor={e} />
+        <ReferenceMenuView editor={e} />
+      </>
+    )
+  }
+
+  it('takes a click on the chip while editing for its menu, and Open hands the click to the chip', async () => {
+    followed.mockClear()
+    render(<Harness content={para({ type: 'text', text: 'See ' }, { type: 'reference', attrs: { uri: V } })} />)
+    const chip = await screen.findByRole('link', { name: 'Item' })
+    fireEvent.click(chip)
+    expect(followed).not.toHaveBeenCalled()
+    await screen.findByRole('menu', { name: 'Link' })
+    fireEvent.mouseDown(screen.getByRole('menuitem', { name: 'Open' }))
+    expect(followed).toHaveBeenCalledWith(V)
+    await waitFor(() => expect(screen.queryByRole('menu', { name: 'Link' })).toBeNull())
+  })
+
+  it('shows the chip\'s card checked, and choosing one sets it and closes', async () => {
+    render(<Harness content={para({ type: 'text', text: 'See ' }, { type: 'reference', attrs: { uri: V } })} />)
+    fireEvent.click(await screen.findByRole('link', { name: 'Item' }))
+    const none = await screen.findByRole('menuitemradio', { name: 'None' })
+    expect(none.getAttribute('aria-checked')).toBe('true')
+    fireEvent.mouseDown(screen.getByRole('menuitemradio', { name: 'Detailed' }))
+    expect(chipOf(editor!)?.attrs?.embed).toBe('detailed')
+    await waitFor(() => expect(screen.queryByRole('menu', { name: 'Link' })).toBeNull())
+  })
+
+  it('lets a click follow the chip when the editor is not editable', async () => {
+    followed.mockClear()
+    render(<Harness content={para({ type: 'text', text: 'See ' }, { type: 'reference', attrs: { uri: V } })} />)
+    const chip = await screen.findByRole('link', { name: 'Item' })
+    act(() => editor!.setEditable(false))
+    fireEvent.click(chip)
+    expect(followed).toHaveBeenCalledWith(V)
+    expect(screen.queryByRole('menu', { name: 'Link' })).toBeNull()
+  })
+})

package/src/ReferenceMenu.tsx

@@ -0,0 +1,346 @@
+/**
+ * What a chip in a document offers its writer — Open, and its card: none,
+ * compact or detailed (SPEC §13.3, "A reference's card").
+ *
+ * **Where it opens** (Miky, 14 Oct): a click on a chip while editing opens the
+ * menu instead of following the chip, and a chip just put in — pasted, picked
+ * with `[`, or a pasted URL becoming its chip (`LinkChips`) — opens it by
+ * itself, so the card can be chosen at once. That menu takes no focus: the
+ * person is still writing, and typing on closes it with no card. Enter on a
+ * selected chip opens it from the keyboard.
+ *
+ * **Keys while it is open**, handed over by the editor as the `/` menu's are:
+ * ↓ and ↑ move through the rows (nothing is highlighted until they do, so
+ * Enter after a paste still starts a new line), Enter chooses the highlighted
+ * row, Escape closes it. Any edit or caret move closes it.
+ *
+ * Open does what a click on the chip does when reading: the app's own chip
+ * gets the click, so it opens where the app opens it. A chip with nothing to
+ * click opens its URL in a new tab.
+ *
+ * Two parts: the extension `ReferenceMenu` holds which chip the menu is open
+ * on, and `ReferenceMenuView` draws it beside `EditorContent`. Pair them with
+ * `ReferenceNode` and `ReferenceCards`.
+ */
+import { useCallback } from 'react'
+import { Extension, type Editor } from '@tiptap/core'
+import { useEditorState } from '@tiptap/react'
+import { NodeSelection, Plugin, PluginKey, TextSelection, type EditorState, type Transaction } from '@tiptap/pm/state'
+import { ReplaceStep } from '@tiptap/pm/transform'
+import type { EditorView } from '@tiptap/pm/view'
+import { IconCheck } from '@tabler/icons-react'
+import { CHIPS_MADE } from './LinkChips'
+import { MenuItem, MenuSection, MenuSeparator } from './Menu'
+import { Popover } from './Popover'
+import { setReferenceCardAt, type ReferenceCardLayout } from './ReferenceCards'
+
+interface MenuState {
+  /** The chip's position. */
+  pos: number
+  /** The highlighted row of `rowsOf`, or -1 for none. */
+  active: number
+}
+
+const key = new PluginKey<MenuState | null>('referenceMenu')
+
+const LAYOUTS: { layout: ReferenceCardLayout; label: string }[] = [
+  { layout: 'none', label: 'None' },
+  { layout: 'compact', label: 'Compact' },
+  { layout: 'detailed', label: 'Detailed' },
+]
+
+/** A row: Open, or a card. */
+type Row = 'open' | ReferenceCardLayout
+
+/** The chip's own control to click, or null. */
+function chipTarget(view: EditorView, pos: number): HTMLElement | null {
+  const dom = view.nodeDOM(pos)
+  return dom instanceof HTMLElement ? dom.querySelector<HTMLElement>('a[href], button') : null
+}
+
+/** An http(s) URL chip's URL, or ''. */
+function webHref(view: EditorView, pos: number): string {
+  const href = view.state.doc.nodeAt(pos)?.attrs.href
+  return typeof href === 'string' && /^https?:\/\//i.test(href) ? href : ''
+}
+
+/**
+ * The menu's rows: Open when there is something to open — the chip's own
+ * control, or its URL — and the cards when the chip names something.
+ */
+function rowsOf(view: EditorView, pos: number): Row[] {
+  const open: Row[] = chipTarget(view, pos) || webHref(view, pos) ? ['open'] : []
+  return view.state.doc.nodeAt(pos)?.attrs.uri ? [...open, ...LAYOUTS.map((card) => card.layout)] : open
+}
+
+/** A chip node, or null. */
+function chipAt(state: EditorState, pos: number) {
+  const node = state.doc.nodeAt(pos)
+  return node && node.type.name === 'reference' ? node : null
+}
+
+/**
+ * The chip this transaction just put right before the caret — a paste, a `[`
+ * pick (which adds a space after it), or a URL becoming its chip — or null.
+ * An undo, and a document loaded over the editor, put nothing in.
+ */
+function justPlaced(tr: Transaction, state: EditorState): number | null {
+  if (!tr.docChanged || tr.getMeta('history$') || tr.getMeta('preventUpdate')) return null
+  // A whole document set over the editor — someone else's edit loaded — is not something the person put in.
+  const whole = tr.steps.some((step) => step instanceof ReplaceStep && step.from === 0 && step.to === tr.before.content.size)
+  if (whole && tr.getMeta('uiEvent') !== 'paste') return null
+  // A URL becoming its chip opens the menu only when it was pasted, with the caret still right after it.
+  const made = tr.getMeta(CHIPS_MADE) as { pasted: boolean } | undefined
+  if (made && !made.pasted) return null
+  const { selection } = state
+  if (!selection.empty) return null
+  let at = selection.from
+  let before = selection.$from.nodeBefore
+  if (!made && before?.isText && before.text === ' ') {
+    at -= 1
+    before = state.doc.resolve(at).nodeBefore
+  }
+  if (!before || before.type.name !== 'reference' || !before.attrs.uri) return null
+  const pos = at - before.nodeSize
+  const old = tr.mapping.invert().map(pos)
+  const was = tr.before.nodeAt(old)
+  // The same chip as before the step — a key pressed after it, a card set on it — is not new. One put in just before
+  // an identical chip pushes that chip along, so it no longer maps onto `pos` (code review).
+  if (was && was.type.name === 'reference' && was.attrs.uri === before.attrs.uri && tr.mapping.map(old, 1) === pos) return null
+  return pos
+}
+
+function dispatchMenu(view: EditorView, next: MenuState | null): void {
+  view.dispatch(view.state.tr.setMeta(key, next))
+}
+
+// True while Open hands the click to the chip, so the chip's own click is not taken for a click that opens the menu.
+let passing = false
+
+/** Opens what the chip at `pos` names, as a click on it does when reading. */
+function openChip(view: EditorView, pos: number): void {
+  const target = chipTarget(view, pos)
+  if (target) {
+    passing = true
+    try {
+      target.click()
+    } finally {
+      passing = false
+    }
+    return
+  }
+  const href = webHref(view, pos)
+  if (href) window.open(href, '_blank', 'noopener,noreferrer')
+}
+
+/** Runs `row` of the menu open on the chip at `pos`, and closes it. */
+function choose(editor: Editor, pos: number, row: Row | undefined): void {
+  dispatchMenu(editor.view, null)
+  if (row === 'open') openChip(editor.view, pos)
+  else if (row) setReferenceCardAt(editor, pos, row)
+}
+
+/** Whether the menu is open, for an editor's own Escape: while it is, Escape closes it rather than leaving. */
+export function isReferenceMenuOpen(state: EditorState): boolean {
+  return !!key.getState(state)
+}
+
+/**
+ * A click on the chip at `pos`, from its node view: while editing, with the
+ * menu installed, it opens the menu, and the caller stops the click there.
+ * Returns false when the click should go on to the chip.
+ */
+export function referenceMenuClick(editor: Editor, pos: number): boolean {
+  if (passing || editor.isDestroyed || !editor.isEditable || key.getState(editor.state) === undefined) return false
+  // A chip with nothing to open and no card to choose has no menu: the click goes on to it.
+  if (!chipAt(editor.state, pos) || rowsOf(editor.view, pos).length === 0) return false
+  editor.view.dispatch(caretAfter(editor.state, pos).setMeta(key, { pos, active: -1 }))
+  return true
+}
+
+/**
+ * The caret right after the chip, as a paste leaves it: a selected chip would
+ * bring up the selection toolbar beside the menu, and typing would replace it.
+ */
+function caretAfter(state: EditorState, pos: number): Transaction {
+  const node = state.doc.nodeAt(pos)
+  return state.tr.setSelection(TextSelection.create(state.doc, pos + (node?.nodeSize ?? 1)))
+}
+
+/** Which chip the menu is open on: see the module comment. */
+export const ReferenceMenu = Extension.create({
+  name: 'referenceMenu',
+  // Before the editor's own keys, so Enter on a highlighted row is the row's, not a new line.
+  priority: 1000,
+  addProseMirrorPlugins() {
+    const editor = this.editor
+    return [
+      new Plugin<MenuState | null>({
+        key,
+        state: {
+          init: () => null,
+          apply: (tr, value, before, after) => {
+            const meta = tr.getMeta(key) as MenuState | null | undefined
+            if (meta !== undefined) return meta
+            const placed = justPlaced(tr, after)
+            if (placed !== null) return { pos: placed, active: -1 }
+            if (!value) return null
+            const pos = tr.mapping.map(value.pos)
+            if (!chipAt(after, pos)) return null
+            // What another plugin appends — an id, a trailing line — is not the person typing on, and nor is a URL
+            // elsewhere becoming its chip when its answer comes back (code review).
+            if (tr.docChanged && !tr.getMeta('appendedTransaction') && tr.getMeta(CHIPS_MADE) === undefined) return null
+            const onChip = after.selection instanceof NodeSelection && after.selection.from === pos
+            if (tr.selectionSet && !after.selection.eq(before.selection) && !onChip) return null
+            return pos === value.pos ? value : { ...value, pos }
+          },
+        },
+        props: {
+          handleDOMEvents: {
+            // Focus gone, the keys no longer reach the menu, and a card chosen now would miss the save on leaving (code review).
+            blur: (view) => {
+              if (key.getState(view.state)) dispatchMenu(view, null)
+              return false
+            },
+          },
+          handleKeyDown: (view, event) => {
+            // With a modifier, a key is the editor's: Shift+↓ extends the selection, Mod+Enter is not a pick.
+            if (event.shiftKey || event.ctrlKey || event.metaKey || event.altKey) return false
+            const open = key.getState(view.state)
+            if (!open) {
+              // Enter on a selected chip: the menu, from the keyboard, its first row highlighted.
+              const { selection } = view.state
+              if (event.key !== 'Enter' || !view.editable || !(selection instanceof NodeSelection) || selection.node.type.name !== 'reference') return false
+              if (rowsOf(view, selection.from).length === 0) return false
+              view.dispatch(caretAfter(view.state, selection.from).setMeta(key, { pos: selection.from, active: 0 }))
+              return true
+            }
+            const rows = rowsOf(view, open.pos)
+            if (event.key === 'Escape') {
+              dispatchMenu(view, null)
+              return true
+            }
+            if (rows.length === 0) return false
+            if (event.key === 'ArrowDown') {
+              dispatchMenu(view, { ...open, active: (open.active + 1) % rows.length })
+              return true
+            }
+            if (event.key === 'ArrowUp') {
+              dispatchMenu(view, { ...open, active: open.active <= 0 ? rows.length - 1 : open.active - 1 })
+              return true
+            }
+            if (event.key === 'Enter' && open.active >= 0) {
+              choose(editor, open.pos, rows[open.active])
+              return true
+            }
+            return false
+          },
+        },
+      }),
+    ]
+  },
+})
+
+/** What the panel draws: the chip the menu is open on, and its card. */
+interface Shown {
+  pos: number
+  active: number
+  named: boolean
+  layout: ReferenceCardLayout
+}
+
+export interface ReferenceMenuViewProps {
+  editor: Editor | null
+}
+
+/** The menu `ReferenceMenu` holds, hung under its chip. Render it always, beside `EditorContent`. */
+export function ReferenceMenuView({ editor }: ReferenceMenuViewProps) {
+  const shown = useEditorState({
+    editor,
+    selector: ({ editor: ed }): Shown | null => {
+      if (!ed || ed.isDestroyed) return null
+      const open = key.getState(ed.state)
+      if (!open) return null
+      const node = chipAt(ed.state, open.pos)
+      if (!node) return null
+      const embed = node.attrs.embed
+      // An unknown layout draws compact (§13.3), so it reads as compact here.
+      const layout: ReferenceCardLayout = embed === 'detailed' ? 'detailed' : typeof embed === 'string' && embed !== '' && embed !== 'none' ? 'compact' : 'none'
+      return { pos: open.pos, active: open.active, named: !!node.attrs.uri, layout }
+    },
+  })
+  // A press anywhere in the panel keeps focus in the text, as a row's does: the editor saves and ends its menus when it loses focus.
+  const keepFocus = useCallback((list: HTMLDivElement | null) => {
+    const panel = list?.closest('[role="dialog"]')
+    if (!panel) return
+    const keep = (event: Event) => event.preventDefault()
+    panel.addEventListener('mousedown', keep)
+    return () => panel.removeEventListener('mousedown', keep)
+  }, [])
+
+  const live = shown && editor && !editor.isDestroyed ? editor : null
+  const dom = live && shown ? live.view.nodeDOM(shown.pos) : null
+  const anchor = dom instanceof HTMLElement ? dom : null
+  const rows = live && shown ? rowsOf(live.view, shown.pos) : []
+  const opens = rows[0] === 'open'
+  const run = (row: Row) => {
+    if (editor && shown) choose(editor, shown.pos, row)
+  }
+
+  return (
+    // finalFocus={false}: focus never left the text.
+    <Popover
+      anchor={anchor}
+      open={!!shown && !!anchor && rows.length > 0}
+      onOpenChange={(next) => {
+        if (!next && editor && !editor.isDestroyed && key.getState(editor.state)) dispatchMenu(editor.view, null)
+      }}
+      side="bottom"
+      align="left"
+      ariaLabel="Link"
+      finalFocus={false}
+    >
+      {shown && (
+        <div ref={keepFocus} role="menu" aria-label="Link" className="flex flex-col gap-0.5">
+          {/* Only when there is something to open: the chip's own control, or its URL (code review). */}
+          {opens && (
+            <MenuItem
+              role="menuitem"
+              tabIndex={-1}
+              label="Open"
+              selected={shown.active === 0}
+              onMouseDown={(event) => {
+                event.preventDefault()
+                run('open')
+              }}
+            />
+          )}
+          {shown.named && (
+            <>
+              {opens && <MenuSeparator />}
+              <div role="group" aria-label="Card">
+                <MenuSection label="Card">
+                  {LAYOUTS.map(({ layout, label }, i) => (
+                    <MenuItem
+                      key={layout}
+                      role="menuitemradio"
+                      aria-checked={shown.layout === layout}
+                      tabIndex={-1}
+                      label={label}
+                      selected={shown.active === i + (opens ? 1 : 0)}
+                      trailing={shown.layout === layout ? <IconCheck size={16} aria-hidden /> : undefined}
+                      onMouseDown={(event) => {
+                        event.preventDefault()
+                        run(layout)
+                      }}
+                    />
+                  ))}
+                </MenuSection>
+              </div>
+            </>
+          )}
+        </div>
+      )}
+    </Popover>
+  )
+}

package/src/RichText.test.tsx

@@ -19,6 +19,23 @@ const row = (typeName: string, ...texts: string[]): RichTextBlock => ({ type: 'u
 const draw = (blocks: RichTextBlock[], props = {}) => render(<RichText blocks={blocks} {...props} />).container
 
 describe('RichText', () => {
+  it('draws renderAfter after a line of words, inside a list item, and nowhere it returns nothing', () => {
+    const after = (block: RichTextBlock) => (block.id === 'skip' ? null : <aside data-after={block.id} />)
+    const c = draw(
+      [
+        { type: 'paragraph', id: 'p1', inline: [t('One')] },
+        { type: 'paragraph', id: 'skip', inline: [t('Two')] },
+        { type: 'bulletList', id: 'l1', children: [{ type: 'listItem', id: 'i1', inline: [t('Item')] }] },
+        { type: 'heading', id: 'h1', level: 2, inline: [t('Head')] },
+      ],
+      { renderAfter: after },
+    )
+    expect([...c.querySelectorAll('[data-after]')].map((e) => e.getAttribute('data-after'))).toEqual(['p1', 'i1', 'h1'])
+    // After its paragraph, not inside it; inside its item, not after the list.
+    expect(c.querySelector('p[data-block-id="p1"] + aside[data-after="p1"]')).not.toBeNull()
+    expect(c.querySelector('li[data-block-id="i1"] > aside[data-after="i1"]')).not.toBeNull()
+  })
+
   it('draws each block as its element', () => {
     const c = draw([
       { type: 'heading', level: 1, inline: [t('One')] },