@estiva-app/ui 0.67.0 → 0.69.0

package/src/LinkChips.test.tsx

@@ -0,0 +1,221 @@
+// @vitest-environment jsdom
+/**
+ * An app URL in a document reads as its chip (SPEC §13.3, §7.7): a URL that
+ * names something becomes a URL chip keeping its URL, one that names nothing or
+ * is not answered yet stays text, and the URL being typed is left alone.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { Editor } from '@tiptap/core'
+import { TextSelection } from '@tiptap/pm/state'
+import StarterKit from '@tiptap/starter-kit'
+import { BlockId, ReferenceNode } from './BlockNodes'
+import { LinkChips, refreshLinkChips } from './LinkChips'
+import { ReferenceCards, referenceAtSelection, referenceCardPlacements } from './ReferenceCards'
+
+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 para = (...content: unknown[]): Record<string, unknown> => ({ type: 'doc', content: [{ type: 'paragraph', attrs: { blockId: 'p1' }, content }] })
+
+let editor: Editor | undefined
+afterEach(() => {
+  editor?.destroy()
+  editor = undefined
+})
+
+const make = (content: Record<string, unknown>, known: Map<string, string>, asked: string[][] = []) => {
+  editor = new Editor({
+    extensions: [
+      // A document editor has no link mark: its URLs are text until they are chips.
+      StarterKit.configure({ link: false }),
+      BlockId,
+      ReferenceNode,
+      ReferenceCards,
+      LinkChips.configure({
+        referenceOf: (url) => known.get(url),
+        ask: (urls) => {
+          asked.push(urls)
+          return Promise.resolve()
+        },
+      }),
+    ],
+    content,
+  })
+  return editor
+}
+
+const tick = () => new Promise((resolve) => setTimeout(resolve, 0))
+
+describe('LinkChips', () => {
+  it('makes a URL that names something its chip on open, keeping the URL and the marks', async () => {
+    const ed = make(para({ type: 'text', text: `See ${URL_}.` }), new Map([[URL_, V]]))
+    await tick()
+    const [before, chip, after] = inline(ed)
+    expect(before.text).toBe('See ')
+    expect(chip.type).toBe('reference')
+    expect(chip.attrs).toMatchObject({ uri: V, href: URL_ })
+    expect(after.text).toBe('.')
+  })
+
+  it('leaves a URL that names nothing as text, and asks the app about it', async () => {
+    const asked: string[][] = []
+    const ed = make(para({ type: 'text', text: `See ${URL_} and https://else.example/x` }), new Map(), asked)
+    await tick()
+    expect(inline(ed)).toHaveLength(1)
+    expect(asked[0]).toEqual([URL_, 'https://else.example/x'])
+  })
+
+  it('asks about each URL once, and no more than its limit', async () => {
+    const asked: string[][] = []
+    editor = new Editor({
+      extensions: [
+        StarterKit.configure({ link: false }),
+        BlockId,
+        ReferenceNode,
+        LinkChips.configure({ referenceOf: () => undefined, ask: (urls) => void asked.push(urls), limit: 2 }),
+      ],
+      content: para({ type: 'text', text: 'https://a.example/1 https://a.example/2 https://a.example/3' }),
+    })
+    await tick()
+    editor.commands.insertContentAt(1, 'x ')
+    expect(asked).toEqual([['https://a.example/1', 'https://a.example/2']])
+  })
+
+  it('turns the URL into its chip once the answer comes back', async () => {
+    const known = new Map<string, string>()
+    const ed = make(para({ type: 'text', text: `See ${URL_} now` }), known)
+    await tick()
+    expect(inline(ed)).toHaveLength(1)
+    known.set(URL_, V)
+    refreshLinkChips(ed)
+    expect(inline(ed)[1].attrs).toMatchObject({ uri: V, href: URL_ })
+  })
+
+  it('leaves the URL the caret is at the end of, and takes it once the person moves on', async () => {
+    const ed = make(para({ type: 'text', text: 'See ' }), new Map([[URL_, V]]))
+    await tick()
+    ed.view.dispatch(ed.state.tr.setSelection(TextSelection.create(ed.state.doc, ed.state.doc.content.size - 1)))
+    ed.view.dispatch(ed.state.tr.insertText(URL_))
+    expect(inline(ed)).toHaveLength(1)
+    ed.view.dispatch(ed.state.tr.insertText(' '))
+    expect(inline(ed)[1].attrs).toMatchObject({ uri: V, href: URL_ })
+  })
+
+  it('fills in a URL chip read from a document once it is answered; until then it offers no card', async () => {
+    const known = new Map<string, string>()
+    const ed = make(para({ type: 'reference', attrs: { uri: '', href: URL_, embed: 'compact' } }), known)
+    await tick()
+    expect(referenceCardPlacements(ed.state.doc)).toEqual([])
+    ed.view.dispatch(ed.state.tr.setSelection(TextSelection.create(ed.state.doc, 1, 2)))
+    expect(referenceAtSelection(ed.state)).toBeNull()
+    known.set(URL_, V)
+    refreshLinkChips(ed)
+    expect(inline(ed)[0].attrs).toMatchObject({ uri: V, href: URL_, embed: 'compact' })
+    expect(referenceCardPlacements(ed.state.doc)[0].cards).toEqual([{ uri: V, layout: 'compact' }])
+  })
+
+  it('dispatches nothing on open when there is no chip to make, so no other plugin wakes', async () => {
+    const ed = make(para({ type: 'text', text: 'Words, no address.' }), new Map([[URL_, V]]))
+    let transactions = 0
+    ed.on('transaction', () => void transactions++)
+    await tick()
+    refreshLinkChips(ed)
+    expect(transactions).toBe(0)
+  })
+
+  it('leaves a URL in code alone', async () => {
+    const ed = make(para({ type: 'text', text: URL_, marks: [{ type: 'code' }] }), new Map([[URL_, V]]))
+    await tick()
+    expect(inline(ed)[0].type).toBe('text')
+  })
+
+  it('takes a pasted URL chip\'s URL and resolves it itself, never the clipboard\'s reference', async () => {
+    const known = new Map<string, string>()
+    const ed = make(para({ type: 'text', text: 'x' }), known)
+    await tick()
+    ed.commands.insertContent(`<p><span data-reference="nostr:naddr1hostile" data-href="${URL_}" data-embed="detailed">${URL_}</span></p>`)
+    const chip = (ed.getJSON() as Json).content?.flatMap((b) => b.content ?? []).find((n) => n.type === 'reference')
+    expect(chip?.attrs).toMatchObject({ uri: '', href: URL_ })
+    expect(referenceCardPlacements(ed.state.doc)).toEqual([])
+  })
+
+  it('drops a pasted URL chip whose href is not http(s)', async () => {
+    const ed = make(para({ type: 'text', text: 'x' }), new Map())
+    await tick()
+    ed.commands.insertContent('<p><span data-reference="nostr:naddr1x" data-href="javascript:alert(1)">x</span></p>')
+    const chip = (ed.getJSON() as Json).content?.flatMap((b) => b.content ?? []).find((n) => n.type === 'reference')
+    expect(chip?.attrs?.href).toBeNull()
+  })
+
+  it('asks nothing while a URL is typed one character at a time, then the whole URL once', async () => {
+    const asked: string[][] = []
+    const ed = make(para({ type: 'text', text: 'See ' }), new Map(), asked)
+    await tick()
+    ed.view.dispatch(ed.state.tr.setSelection(TextSelection.create(ed.state.doc, ed.state.doc.content.size - 1)))
+    for (const ch of URL_) ed.view.dispatch(ed.state.tr.insertText(ch))
+    expect(asked).toEqual([])
+    ed.view.dispatch(ed.state.tr.insertText(' '))
+    expect(asked).toEqual([[URL_]])
+  })
+
+  it('turns a URL with the caret before it, but not one under a selection', async () => {
+    const ed = make(para({ type: 'text', text: `${URL_} end` }), new Map([[URL_, V]]))
+    await tick()
+    // The editor opens with the caret at the URL's start: it is not being typed.
+    expect(inline(ed)[0].type).toBe('reference')
+    ed.commands.setContent(para({ type: 'text', text: `see ${URL_}` }))
+    ed.view.dispatch(ed.state.tr.setSelection(TextSelection.create(ed.state.doc, 10, 14)))
+    expect(inline(ed)).toHaveLength(1)
+  })
+
+  it('copies a URL chip as its URL', async () => {
+    const ed = make(para({ type: 'text', text: `${URL_} ` }), new Map([[URL_, V]]))
+    await tick()
+    expect(ed.getText()).toBe(`${URL_} `)
+  })
+
+  it('makes a pasted URL its chip as its own undo step: undo gives the URL back, then takes the paste away', async () => {
+    const ed = make(para({ type: 'text', text: 'See ' }), new Map([[URL_, V]]))
+    await tick()
+    ed.view.dispatch(ed.state.tr.setSelection(TextSelection.create(ed.state.doc, ed.state.doc.content.size - 1)))
+    ed.view.pasteText(URL_, new Event('paste') as ClipboardEvent)
+    expect(inline(ed).map((n) => n.type)).toEqual(['text', 'reference'])
+    ed.commands.undo()
+    expect(inline(ed)).toEqual([{ type: 'text', text: `See ${URL_}` }])
+    ed.commands.undo()
+    expect(inline(ed)).toEqual([{ type: 'text', text: 'See ' }])
+  })
+
+  it('makes a pasted URL answered later its own undo step too', async () => {
+    const known = new Map<string, string>()
+    const ed = make(para({ type: 'text', text: 'See ' }), known)
+    await tick()
+    ed.view.dispatch(ed.state.tr.setSelection(TextSelection.create(ed.state.doc, ed.state.doc.content.size - 1)))
+    ed.view.pasteText(URL_, new Event('paste') as ClipboardEvent)
+    expect(inline(ed)).toEqual([{ type: 'text', text: `See ${URL_}` }])
+    known.set(URL_, V)
+    refreshLinkChips(ed)
+    expect(inline(ed)[1].type).toBe('reference')
+    ed.commands.undo()
+    expect(inline(ed)).toEqual([{ type: 'text', text: `See ${URL_}` }])
+  })
+
+  it('turns a link whose text is its own URL into its chip, and leaves a link on words', async () => {
+    editor = new Editor({
+      // A composer's link mark: an autolink, or its paste rule, links a bare URL to itself.
+      extensions: [StarterKit.configure({ link: { autolink: false, openOnClick: false } }), BlockId, ReferenceNode, LinkChips.configure({ referenceOf: (url) => (url === URL_ ? V : undefined), ask: null })],
+      content: para(
+        { type: 'text', text: URL_, marks: [{ type: 'link', attrs: { href: URL_ } }, { type: 'bold' }] },
+        { type: 'text', text: ' and ' },
+        { type: 'text', text: 'the words', marks: [{ type: 'link', attrs: { href: URL_ } }] },
+      ),
+    })
+    await tick()
+    const [chip, , words] = inline(editor)
+    expect(chip.type).toBe('reference')
+    expect(chip.attrs).toMatchObject({ uri: V, href: URL_, marks: ['bold'] })
+    expect(words).toMatchObject({ type: 'text', text: 'the words' })
+  })
+})

package/src/LinkChips.ts

@@ -0,0 +1,252 @@
+/**
+ * An app URL in a document reads as the chip of what it names — SPEC §13.3,
+ * "A reference's card", and §7.7.
+ *
+ * The URL stays the URL: the chip is the `reference` node with `href` set (a
+ * URL chip, `ReferenceNode`), which a document writes back as the URL it was,
+ * plain text with no card and a `link` mark with one. Never a `nostr:`
+ * reference in its place: the URL is how a person addresses the object.
+ *
+ * What a URL names is the app's to say — its manifests and its relay — so the
+ * app hands this extension two functions: `referenceOf`, what it has resolved
+ * so far, and `ask`, to look up the URLs it has not. A URL that names nothing,
+ * or whose answer has not come back, stays text; when `ask` settles the
+ * document is looked at again.
+ *
+ * The URL being typed stays text while the caret is in it or at its end, so a
+ * half-typed address never turns into a chip under the person's fingers. A
+ * pasted URL is whole, so it is asked about and made a chip at once, the caret
+ * still at its end — where `ReferenceMenu` opens its menu.
+ */
+import { Extension, type Editor } from '@tiptap/core'
+import { closeHistory } from '@tiptap/pm/history'
+import type { Node as PmNode } from '@tiptap/pm/model'
+import { Plugin, PluginKey, type EditorState, type Selection, type Transaction } from '@tiptap/pm/state'
+
+export interface LinkChipsOptions {
+  /**
+   * The `nostr:` reference an app URL names, from what the app has resolved
+   * (§7.7) — protocol's `referenceOfLink(url, resolveLink)`. Undefined while it
+   * names nothing, or its answer has not come back.
+   */
+  referenceOf: ((url: string) => string | undefined) | null
+  /** Look up what these URLs name. When it settles, the document is looked at again. */
+  ask: ((urls: string[]) => Promise<unknown> | void) | null
+  /**
+   * How many URLs one editor asks about in its life, the first ones; the rest
+   * stay text. An app's answer can cost a relay query, and a document pasted
+   * full of links must not spend the writer's quota. Default 24.
+   */
+  limit: number
+}
+
+interface LinkChipsState {
+  options: LinkChipsOptions
+  /** The last few pastes, mapped through every edit since. */
+  pasted: PastedRange[]
+}
+
+const key = new PluginKey<LinkChipsState>('linkChips')
+
+/** The meta on the transaction that made chips: `{ pasted }`. */
+export const CHIPS_MADE = 'linkChipsMade'
+
+/** How many pastes are remembered; one is what the person just did. */
+const PASTES_KEPT = 8
+
+/**
+ * A link on words in marker text (skipped), or a bare URL — the grammar of
+ * protocol's `urlRunsIn`, which a reader turns into chips by, so what an editor
+ * makes a chip is what a reader would.
+ */
+const LINK_OR_URL = /(\[[^[\]\n]+\]\((?:https?:\/\/|mailto:)[^\s)]+\))|(https?:\/\/[^\s<>"'`]+)/g
+const TRAILING = new Set(['.', ',', ';', ':', '!', '?', ')', ']'])
+
+/** Each URL and where it sits; `end` is where its run ends before trailing punctuation is trimmed, which typing may yet continue. */
+function urlRuns(text: string): { url: string; from: number; to: number; end: number }[] {
+  if (!text.includes('://')) return []
+  const out: { url: string; from: number; to: number; end: number }[] = []
+  for (const m of text.matchAll(LINK_OR_URL)) {
+    if (m[1]) continue
+    const start = m.index
+    if (text.slice(Math.max(0, start - 2), start) === '](' || text[start - 1] === '[') continue
+    let end = m[0].length
+    while (end > 0 && TRAILING.has(m[0][end - 1])) end--
+    out.push({ url: m[0].slice(0, end), from: start, to: start + end, end: start + m[0].length })
+  }
+  return out
+}
+
+interface Found {
+  /** Text URLs that name something: made chips. */
+  chips: { from: number; to: number; url: string; uri: string; marks: string[]; pasted: boolean }[]
+  /** URL chips whose URL is answered now: given their reference. */
+  fills: { pos: number; uri: string }[]
+  /** Every URL still waiting for an answer, or naming nothing. */
+  open: string[]
+}
+
+/** Where something was pasted: a URL wholly inside one was not typed, so the caret at its end does not hold it as text. */
+export interface PastedRange {
+  from: number
+  to: number
+}
+
+/**
+ * What to change in a document, and what to ask. `selection` null treats no
+ * URL as being typed; a URL inside one of `pasted` is never being typed.
+ */
+export function findLinkChips(doc: PmNode, selection: Selection | null, referenceOf: LinkChipsOptions['referenceOf'], pasted: readonly PastedRange[] = []): Found {
+  const found: Found = { chips: [], fills: [], open: [] }
+  const open = new Set<string>()
+  doc.descendants((node, pos) => {
+    // A fence is literal (§13.1): its URLs are text.
+    if (node.type.spec.code) return false
+    if (node.type.name === 'reference') {
+      const href = typeof node.attrs.href === 'string' ? node.attrs.href : ''
+      if (href && !node.attrs.uri) {
+        const uri = referenceOf?.(href)
+        if (uri) found.fills.push({ pos, uri })
+        else open.add(href)
+      }
+      return false
+    }
+    if (!node.isText || !node.text) return true
+    // A URL in code is literal.
+    if (node.marks.some((m) => m.type.spec.code || m.type.name === 'code')) return false
+    // A link on words is the link's. A link whose text is its own URL — an editor's autolink, or its paste rule — is
+    // that URL, as a document reads one (protocol's `inlineToEditor`): its chip, with the link mark left behind.
+    const link = node.marks.find((m) => m.type.name === 'link')
+    if (link && !(link.attrs.href === node.text && /^https?:\/\//.test(node.text))) return false
+    const runs = link ? [{ url: node.text, from: 0, to: node.text.length, end: node.text.length }] : urlRuns(node.text)
+    for (const run of runs) {
+      const from = pos + run.from
+      const to = pos + run.to
+      // Being typed or selected: the caret inside it or at its end (`https://a.` is still being typed), or a
+      // selection over any of it. A caret before it is not.
+      // A pasted URL is whole: it becomes its chip with the caret still at its end, so its menu can open at once.
+      const wasPasted = pasted.some((range) => range.from <= from && pos + run.end <= range.to)
+      const typing = selection && selection.to > from && selection.from <= pos + run.end
+      if (typing && !(selection.empty && wasPasted)) continue
+      const uri = referenceOf?.(run.url)
+      if (uri) found.chips.push({ from, to, url: run.url, uri, marks: node.marks.filter((m) => m !== link).map((m) => m.type.name), pasted: wasPasted })
+      else open.add(run.url)
+    }
+    return false
+  })
+  found.open = [...open]
+  return found
+}
+
+function apply(state: EditorState, found: Found): Transaction | null {
+  if (!found.chips.length && !found.fills.length) return null
+  const type = state.schema.nodes.reference
+  if (!type) return null
+  const tr = state.tr
+  // A fill keeps the node's size, so the chips' positions still hold; the chips go last first.
+  for (const { pos, uri } of found.fills) {
+    const node = tr.doc.nodeAt(pos)
+    if (node) tr.setNodeMarkup(pos, undefined, { ...node.attrs, uri })
+  }
+  for (const chip of [...found.chips].reverse()) {
+    tr.replaceWith(chip.from, chip.to, type.create({ uri: chip.uri, href: chip.url, marks: chip.marks }))
+  }
+  // Whether a pasted URL became its chip: `ReferenceMenu` opens on that one, never on a URL typed by hand.
+  const pasted = found.chips.some((chip) => chip.pasted)
+  tr.setMeta(CHIPS_MADE, { pasted })
+  // A pasted URL's chip is its own undo step, so Ctrl+Z gives the URL back rather than taking the paste away (OPT-19,
+  // as Peek's pasted link did). Any other chip is not a step of the person's: undo takes back what they typed.
+  return pasted ? closeHistory(tr) : tr.setMeta('addToHistory', false)
+}
+
+/**
+ * Look at the document again — after the app learned what more URLs name some
+ * other way. Dispatches only when there is a chip to make: an empty
+ * transaction would wake every other plugin (a trailing paragraph appears).
+ */
+export function refreshLinkChips(editor: Editor): void {
+  if (editor.isDestroyed) return
+  const chips = key.getState(editor.state)
+  if (!chips) return
+  const tr = apply(editor.state, findLinkChips(editor.state.doc, editor.state.selection, chips.options.referenceOf, chips.pasted))
+  if (tr) editor.view.dispatch(tr)
+}
+
+/**
+ * Turns the app URLs in a document into URL chips. Pair it with `ReferenceNode`;
+ * `ReferenceCards` then draws a card a URL chip asks for.
+ */
+export const LinkChips = Extension.create<LinkChipsOptions>({
+  name: 'linkChips',
+  addOptions() {
+    return { referenceOf: null, ask: null, limit: 24 }
+  },
+  addProseMirrorPlugins() {
+    const options = this.options
+    const editor = this.editor
+    return [
+      new Plugin<LinkChipsState>({
+        key,
+        // The options, where `refreshLinkChips` can read them from the state alone, and where the last pastes landed.
+        state: {
+          init: () => ({ options, pasted: [] }),
+          apply: (tr, value, before, after) => {
+            if (!tr.docChanged) return value
+            // A paste edited inside is being typed again: forgotten, so each keystroke in it is not an ask (security review).
+            const pasted = value.pasted
+              .map((range) => ({ from: tr.mapping.map(range.from, 1), to: tr.mapping.map(range.to, -1), size: range.to - range.from }))
+              .filter((range) => range.from < range.to && range.to - range.from === range.size)
+              .map(({ from, to }) => ({ from, to }))
+            if (tr.getMeta('uiEvent') === 'paste') {
+              const from = tr.mapping.map(before.selection.from, -1)
+              if (from < after.selection.to) pasted.push({ from, to: after.selection.to })
+            }
+            return { options, pasted: pasted.slice(-PASTES_KEPT) }
+          },
+        },
+        appendTransaction: (trs, _old, state) => {
+          if (!trs.some((tr) => tr.docChanged || tr.selectionSet)) return null
+          return apply(state, findLinkChips(state.doc, state.selection, options.referenceOf, key.getState(state)?.pasted))
+        },
+        view: (view) => {
+          // Each URL is asked once; one whose ask failed is forgotten, so a later look asks again.
+          const asked = new Set<string>()
+          // The URL being typed is not asked about: each prefix of it would spend one of `limit`, and a query.
+          const look = (state: EditorState) => {
+            if (!options.ask) return
+            const { open } = findLinkChips(state.doc, state.selection, options.referenceOf, key.getState(state)?.pasted)
+            const fresh = open.filter((url) => !asked.has(url)).slice(0, Math.max(0, options.limit - asked.size))
+            if (!fresh.length) return
+            for (const url of fresh) asked.add(url)
+            const forget = () => {
+              for (const url of fresh) asked.delete(url)
+            }
+            let answer: Promise<unknown> | void
+            try {
+              answer = options.ask(fresh)
+            } catch {
+              forget()
+              return
+            }
+            void Promise.resolve(answer).then(() => refreshLinkChips(editor), forget)
+          }
+          look(view.state)
+          // Once the view is up, so a dispatch lands: what the app already knows turns into chips on open.
+          queueMicrotask(() => {
+            try {
+              refreshLinkChips(editor)
+            } catch {
+              // Unmounted before it ran.
+            }
+          })
+          return {
+            update: (next, prev) => {
+              // A caret leaving a URL finishes it, so a move is looked at as an edit is.
+              if (next.state.doc !== prev.doc || !next.state.selection.eq(prev.selection)) look(next.state)
+            },
+          }
+        },
+      }),
+    ]
+  },
+})

package/src/ReferenceCards.mdx

@@ -0,0 +1,79 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks'
+import * as ReferenceCardsStories from './ReferenceCards.stories'
+
+<Meta of={ReferenceCardsStories} />
+
+# ReferenceCards
+
+A chip in a document can ask for a card after its line: compact, detailed or
+none. The choice is the chip's own `embed`, so the card moves and goes with it.
+This draws no card itself. It places a slot after each line that asks for
+one, and the app draws its own card into it.
+
+<Canvas of={ReferenceCardsStories.InAnEditor} />
+
+## When
+
+- **An editor of a document whose chips can carry a card**: pair it with
+  **ReferenceNode**, which holds the choice, and **SelectionToolbar**, where
+  the app offers it for the selected chip.
+
+## When not
+
+- A document that is only read → **RichText**, with each block's cards drawn
+  after it from the text's own description of them.
+- A text whose cards travel beside it rather than on its chips → the app keeps
+  that choice itself, and this has nothing to read.
+
+## How
+
+```tsx
+import { createPortal } from 'react-dom'
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { ToolbarButton } from '@estiva-app/ui'
+import {
+  BlockId,
+  ReferenceCards,
+  ReferenceNode,
+  SelectionToolbar,
+  referenceAtSelection,
+  setReferenceCard,
+  useReferenceCards,
+  type ReferenceCard,
+  type ReferenceViewProps,
+} from '@estiva-app/ui/editor'
+
+const Reference = ({ uri }: ReferenceViewProps) => <span>{uri}</span>
+const Cards = ({ cards }: { cards: ReferenceCard[] }) => <div>{cards.map((card) => card.layout).join(', ')}</div>
+
+const editor = useEditor({ extensions: [StarterKit, BlockId, ReferenceNode.configure({ view: Reference }), ReferenceCards] })
+const slots = useReferenceCards(editor)
+const chip = editor ? referenceAtSelection(editor.state) : null
+
+;<>
+  <EditorContent editor={editor} />
+  {slots.map((slot) => createPortal(<Cards cards={slot.cards} />, slot.element, slot.key))}
+  <SelectionToolbar editor={editor}>
+    {chip && editor && (
+      <ToolbarButton aria-label="Detailed" pressed={chip.layout === 'detailed'} onMouseDown={(e) => e.preventDefault()} onClick={() => setReferenceCard(editor, chip.layout === 'detailed' ? 'none' : 'detailed')}>
+        D
+      </ToolbarButton>
+    )}
+  </SelectionToolbar>
+</>
+```
+
+- **A slot keeps its element while its line lives.** It is keyed by the
+  line's block id, so typing above a card does not make it load again.
+- **The slot is not text.** It cannot be typed into or selected, and a click
+  on a card stays the card's.
+- **A layout this version does not know draws as compact.** The writer asked
+  for a card, and the smallest is the safe reading.
+- **Press without taking the focus.** A button in the toolbar prevents its
+  press's default, or the editor loses the chip's selection and the toolbar
+  goes.
+
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.

package/src/ReferenceCards.stories.tsx

@@ -0,0 +1,64 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+// @estiva-escape(no-hand-rolled-behaviour): the slots ReferenceCards places inside the document are drawn into by a portal, which keeps the app's providers around its card
+import { createPortal } from 'react-dom'
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { BlockId, ReferenceNode } from './BlockNodes'
+import { Card } from './Card'
+import { ReferenceCards, useReferenceCards } from './ReferenceCards'
+import { richTextClassName } from './RichText'
+
+/**
+ * A chip that asks for a card gets a slot after its line, and the app draws
+ * its card there. Here the "card" is a stand-in box naming the layout: the real
+ * one is the app's, which knows how to resolve what the chip points at.
+ */
+const meta = {
+  title: 'Primitives/ReferenceCards',
+  parameters: { layout: 'padded' },
+} satisfies Meta
+
+export default meta
+type Story = StoryObj
+
+const ref = (uri: string, embed?: string) => ({ type: 'reference', attrs: { uri, ...(embed ? { embed } : {}) } })
+
+function Box() {
+  const editor = useEditor({
+    extensions: [StarterKit, BlockId, ReferenceNode, ReferenceCards],
+    content: {
+      type: 'doc',
+      content: [
+        { type: 'paragraph', attrs: { blockId: 'p1' }, content: [{ type: 'text', text: 'Blocked by ' }, ref('nostr:naddr1first', 'detailed'), { type: 'text', text: ' until it ships.' }] },
+        { type: 'paragraph', attrs: { blockId: 'p2' }, content: [{ type: 'text', text: 'See also ' }, ref('nostr:naddr1second')] },
+        { type: 'paragraph', attrs: { blockId: 'p3' }, content: [ref('nostr:naddr1third', 'compact')] },
+      ],
+    },
+    editorProps: { attributes: { class: richTextClassName('default', 'outline-none'), 'aria-label': 'Text' } },
+  })
+  const slots = useReferenceCards(editor)
+  // @estiva-escape(no-hand-rolled-behaviour): the app's card goes into the slot ReferenceCards placed after its line, inside the document; no Base UI part owns a place in an editor's text
+  return (
+    <Card fill="surface" className="flex w-[520px] flex-col gap-2 p-3">
+      <EditorContent editor={editor} />
+      {slots.map((slot) =>
+        createPortal(
+          <div className="mt-2 flex flex-col gap-2">
+            {slot.cards.map((card, i) => (
+              <Card key={`${card.uri}-${i}`} fill="surface" className="p-3">
+                <span className="text-body-2 text-text-secondary">
+                  {card.layout} card for {card.uri}
+                </span>
+              </Card>
+            ))}
+          </div>,
+          slot.element,
+          slot.key,
+        ),
+      )}
+    </Card>
+  )
+}
+
+/** Three chips: a detailed card after the first line, none for the second, a compact one after the third. */
+export const InAnEditor: Story = { render: () => <Box /> }