tiptapify 0.3.5 → 0.4.0

package/src/extensions/components/media/link/index.ts

@@ -1,24 +1,129 @@
 import { CommandProps } from '@tiptap/core'
 import Link from '@tiptap/extension-link'
+import { Node as ProseMirrorNode } from '@tiptap/pm/model'
+import { EditorState, Plugin, PluginKey, Transaction } from '@tiptap/pm/state'
+import { getLinkContext, LINK_MARK } from '@tiptapify/extensions/components/media/link/linkDialog'
+import { LinkCardDraft, selectedLinkCard } from '@tiptapify/extensions/components/media/linkCard'
 
 declare module '@tiptap/core' {
   interface Commands<ReturnType> {
     tiptapify_link: {
-      showLink: () => ReturnType
+      showLink: (card?: LinkCardDraft) => ReturnType
     }
   }
 }
 
+const LEGACY_LINK = 'tiptapify_link'
+
+function hasLegacyLinks(doc: ProseMirrorNode): boolean {
+  let found = false
+  doc.descendants((node) => {
+    found ||= node.marks.some(mark => mark.type.name === LEGACY_LINK)
+
+    return !found
+  })
+
+  return found
+}
+
+/**
+ * The `tiptapify_link` marks of a document as `link` marks: a text that had both keeps its `link`, one that
+ * had only the legacy mark gets a `link` with its attributes. Null when there is nothing to change.
+ */
+export function migrateLegacyLinks(state: EditorState): Transaction | null {
+  const legacy = state.schema.marks[LEGACY_LINK]
+  const link = state.schema.marks[LINK_MARK]
+  if (!legacy || !link || !hasLegacyLinks(state.doc)) {
+    return null
+  }
+
+  const tr = state.tr
+  state.doc.descendants((node, pos) => {
+    const old = node.marks.find(mark => mark.type === legacy)
+    if (!old) {
+      return
+    }
+
+    const end = pos + node.nodeSize
+    tr.removeMark(pos, end, legacy)
+    if (!link.isInSet(node.marks)) {
+      const attrs = Object.fromEntries(Object.keys(link.spec.attrs ?? {}).map(name => [name, old.attrs[name] ?? null]))
+      tr.addMark(pos, end, link.create(attrs))
+    }
+  })
+
+  return tr.setMeta('addToHistory', false)
+}
+
+type JSONNode = { marks?: { type: string, attrs?: Record<string, unknown> }[], content?: JSONNode[], [key: string]: unknown }
+
+/**
+ * The same for the JSON content an editor starts with, before its document is made.
+ */
+export function migrateLegacyLinkJSON(node: JSONNode): JSONNode {
+  const marks = node.marks?.some(mark => mark.type === LEGACY_LINK)
+    ? node.marks
+      .filter(mark => mark.type !== LEGACY_LINK || !node.marks!.some(other => other.type === LINK_MARK))
+      .map(mark => (mark.type === LEGACY_LINK ? { ...mark, type: LINK_MARK } : mark))
+    : node.marks
+
+  return {
+    ...node,
+    ...(marks ? { marks } : {}),
+    ...(node.content ? { content: node.content.map(migrateLegacyLinkJSON) } : {}),
+  }
+}
+
+/**
+ * The link dialog command. Links themselves are the `link` mark; the legacy `tiptapify_link` mark stays in the
+ * schema only so saved JSON that still has it loads, and its marks turn into `link` as they load.
+ */
 export const TiptapifyLink = Link.extend({
-  name: 'tiptapify_link',
+  name: LEGACY_LINK,
+
+  // `link` reads the links of HTML
+  parseHTML() {
+    return []
+  },
+
+  // No paste rules or commands of its own (`setLink`/`unsetLink` act on `link`): a second link mark would nest links
+  addPasteRules() {
+    return []
+  },
+
+  addProseMirrorPlugins() {
+    return [
+      new Plugin({
+        key: new PluginKey('tiptapifyLegacyLinks'),
+        appendTransaction: (transactions, _oldState, newState) => (
+          transactions.some(tr => tr.docChanged) ? migrateLegacyLinks(newState) : null
+        ),
+      }),
+    ]
+  },
+
+  onBeforeCreate() {
+    const { content } = this.editor.options
+    if (content && typeof content === 'object' && !Array.isArray(content)) {
+      this.editor.options.content = migrateLegacyLinkJSON(content as JSONNode) as never
+    }
+  },
 
   addCommands() {
     return {
-      ...this.parent?.(),
-      showLink: () => ({ editor }: CommandProps) => {
+      showLink: card => ({ editor }: CommandProps) => {
+        const { active, attrs, text } = getLinkContext(editor)
+
+        // `link`: the attributes of the link being edited (empty when inserting a new one);
+        // `text`: its text, or the text of the selection; `card`: the selected card to edit;
+        // `draft`: an address to make a card of (the dialog opens showing it as a card)
         const event = new CustomEvent('tiptapify-show-link', {
           detail: {
-            link: editor.getAttributes('link'),
+            link: attrs,
+            active,
+            text,
+            card: selectedLinkCard(editor),
+            draft: card ?? null,
             editorId: editor.instanceId
           }
         })
@@ -29,4 +134,4 @@ export const TiptapifyLink = Link.extend({
       },
     }
   },
-})
+})

package/src/extensions/components/media/link/link.marks.test.ts

@@ -0,0 +1,89 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { Editor } from '@tiptap/core'
+import { editorExtensions } from '@tiptapify/components/editorExtensions'
+
+// jsdom has no ClipboardEvent, which a paste of the editor creates
+globalThis.ClipboardEvent ??= class extends Event {
+  clipboardData = null
+} as never
+
+let editor: Editor | null = null
+
+function createEditor(content: string | Record<string, unknown> = '<p></p>') {
+  editor = new Editor({ element: document.createElement('div'), content, extensions: editorExtensions('', false, []) })
+
+  return editor
+}
+
+function markNames(): string[] {
+  const names: string[] = []
+  editor!.state.doc.descendants((node) => {
+    node.marks.forEach(mark => names.push(mark.type.name))
+  })
+
+  return names
+}
+
+const anchors = () => (editor!.getHTML().match(/<a /g) ?? []).length
+
+describe('one link mark', () => {
+  afterEach(() => {
+    editor?.destroy()
+    editor = null
+  })
+
+  it('makes one link of a pasted URL, not a link inside a link', () => {
+    createEditor()
+
+    editor!.view.pasteText('https://www.w3schools.com/')
+
+    expect(anchors()).toBe(1)
+    expect(markNames()).toEqual(['link'])
+  })
+
+  it('reads a link of the saved HTML as one link', () => {
+    createEditor('<p>Read <a href="https://example.com">this</a></p>')
+
+    expect(anchors()).toBe(1)
+    expect(markNames()).toEqual(['link'])
+  })
+
+  it('sets and removes links with the link mark', () => {
+    createEditor('<p>Read this</p>')
+
+    editor!.chain().setTextSelection({ from: 6, to: 10 }).setLink({ href: 'https://example.com' }).run()
+    expect(markNames()).toEqual(['link'])
+
+    editor!.chain().setTextSelection({ from: 6, to: 10 }).unsetLink().run()
+    expect(markNames()).toEqual([])
+  })
+
+  it('loads the saved JSON of earlier versions (tiptapify_link marks) as one link', () => {
+    const saved = {
+      type: 'doc',
+      content: [{
+        type: 'paragraph',
+        content: [{
+          type: 'text',
+          text: 'site',
+          marks: [
+            { type: 'link', attrs: { href: 'https://example.com' } },
+            { type: 'tiptapify_link', attrs: { href: 'https://example.com' } },
+          ],
+        }, {
+          type: 'text',
+          text: ' and old',
+          marks: [{ type: 'tiptapify_link', attrs: { href: 'https://old.example.com', target: '_blank' } }],
+        }],
+      }],
+    }
+
+    createEditor(saved)
+    expect(editor!.getHTML()).toBe('<p><a target="_blank" rel="noopener noreferrer nofollow" href="https://example.com">site</a><a target="_blank" rel="noopener noreferrer nofollow" href="https://old.example.com"> and old</a></p>')
+    expect(markNames().every(name => name === 'link')).toBe(true)
+
+    editor!.commands.setContent(saved)
+    expect(markNames().every(name => name === 'link')).toBe(true)
+    expect(anchors()).toBe(2)
+  })
+})

package/src/extensions/components/media/link/linkDialog.test.ts

@@ -0,0 +1,296 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { Editor } from '@tiptap/vue-3'
+import { Document } from '@tiptap/extension-document'
+import { Paragraph } from '@tiptap/extension-paragraph'
+import { Text } from '@tiptap/extension-text'
+import { Link } from '@tiptap/extension-link'
+import { TiptapifyLink } from '@tiptapify/extensions/components/media/link'
+import { LinkCard, LinkCardAttrs } from '@tiptapify/extensions/components/media/linkCard'
+import {
+  applyLink,
+  formRel,
+  getLinkContext,
+  hasAdvancedValues,
+  LinkForm,
+  linkAttrs,
+  linkToCard,
+  missingProtocol,
+  parseRel,
+  removeLink,
+  serializeRel,
+  withProtocol,
+  withNewTabRel,
+} from '@tiptapify/extensions/components/media/link/linkDialog'
+
+describe('missingProtocol', () => {
+  it.each([
+    'example.com',
+    '  www.example.com/page?x=1#top ',
+    'internal.com:21',
+    'sub.example.co.uk:8080/path',
+    'localhost:8080/admin',
+    'intranet:3000',
+  ])('%s needs a protocol', (href) => {
+    expect(missingProtocol(href)).toBe(true)
+  })
+
+  it.each([
+    'http://example.com',
+    'HTTPS://example.com',
+    'ftp://files.example.com',
+    'smb://server/share',
+    'mailto:user@example.com',
+    'tel:+380441234567',
+    '#anchor',
+    '/relative/path',
+    './page',
+    '../page',
+    '?query=1',
+    'user@example.com',
+    'word',
+    '',
+  ])('%s does not', (href) => {
+    expect(missingProtocol(href)).toBe(false)
+  })
+})
+
+describe('withProtocol', () => {
+  it('puts the chosen protocol before the address', () => {
+    expect(withProtocol(' internal.com:21 ', 'ftp')).toBe('ftp://internal.com:21')
+    expect(withProtocol('intranet/wiki', 'http')).toBe('http://intranet/wiki')
+  })
+})
+
+describe('rel helpers', () => {
+  it('parses an attribute string and pasted lists', () => {
+    expect(parseRel(' NoFollow  ugc,sponsored ')).toEqual(['nofollow', 'ugc', 'sponsored'])
+    expect(parseRel(['nofollow', 'ugc, nofollow', ' Me '])).toEqual(['nofollow', 'ugc', 'me'])
+    expect(parseRel(null)).toEqual([])
+  })
+
+  it('serializes to an attribute or null', () => {
+    expect(serializeRel(['nofollow', 'NOFOLLOW', 'ugc'])).toBe('nofollow ugc')
+    expect(serializeRel([])).toBeNull()
+  })
+
+  it('adds noopener noreferrer for a new tab only', () => {
+    expect(withNewTabRel(['nofollow'], true)).toEqual(['nofollow', 'noopener', 'noreferrer'])
+    expect(withNewTabRel(['noopener'], true)).toEqual(['noopener', 'noreferrer'])
+    expect(withNewTabRel(['nofollow'], false)).toEqual(['nofollow'])
+  })
+
+  it('hides the values implied by a new tab in the form', () => {
+    expect(formRel('noopener noreferrer nofollow', true)).toEqual(['nofollow'])
+    expect(formRel('noopener nofollow', false)).toEqual(['noopener', 'nofollow'])
+  })
+
+  it('detects settings of the advanced section', () => {
+    expect(hasAdvancedValues(['noopener', 'noreferrer'], '')).toBe(false)
+    expect(hasAdvancedValues(['nofollow'], '')).toBe(true)
+    expect(hasAdvancedValues([], ' btn ')).toBe(true)
+  })
+
+  it('builds mark attributes', () => {
+    const form: LinkForm = { href: ' ftp://example.com ', text: '', newTab: false, rel: [], cssClass: ' ' }
+
+    expect(linkAttrs(form)).toEqual({ href: 'ftp://example.com', target: null, rel: null, class: null })
+    expect(linkAttrs({ ...form, newTab: true, rel: ['ugc'], cssClass: 'btn' }))
+      .toEqual({ href: 'ftp://example.com', target: '_blank', rel: 'ugc noopener noreferrer', class: 'btn' })
+  })
+})
+
+describe('apply logic', () => {
+  let editor: Editor | null = null
+
+  function createEditor(content: string) {
+    editor = new Editor({
+      element: document.createElement('div'),
+      content,
+      // The same pair of link extensions the editor registers
+      extensions: [
+        Document,
+        Paragraph,
+        Text,
+        Link.configure({ openOnClick: false, enableClickSelection: true, defaultProtocol: 'https' }),
+        TiptapifyLink.configure({ openOnClick: false, defaultProtocol: 'https' }),
+      ],
+    })
+
+    return editor
+  }
+
+  function form(overrides: Partial<LinkForm> = {}): LinkForm {
+    return { href: 'https://example.com', text: '', newTab: false, rel: [], cssClass: '', ...overrides }
+  }
+  it('never adds a protocol of its own: the address is saved as typed', () => {
+    const ed = createEditor('<p>intranet</p>')
+    ed.commands.setTextSelection({ from: 1, to: 9 })
+
+    applyLink(ed, form({ href: ' ftp://internal.com:21/report.zip ', text: 'intranet' }), getLinkContext(ed))
+
+    expect(ed.getHTML()).toContain('href="ftp://internal.com:21/report.zip"')
+  })
+
+
+
+  afterEach(() => {
+    editor?.destroy()
+    editor = null
+  })
+
+  it('inserts the text with the link on an empty selection', () => {
+    const ed = createEditor('<p>Hello world</p>')
+    ed.commands.setTextSelection(7)
+    const context = getLinkContext(ed)
+
+    expect(context).toEqual({ active: false, attrs: {}, text: '' })
+    expect(applyLink(ed, form({ text: 'site' }), context)).toBe(true)
+    expect(ed.getHTML()).toBe('<p>Hello <a href="https://example.com">site</a>world</p>')
+
+    // Typing right after the new link does not extend it
+    ed.commands.insertContent(' ')
+    expect(ed.getHTML()).toBe('<p>Hello <a href="https://example.com">site</a> world</p>')
+  })
+
+  it('uses the address as the text when both are empty', () => {
+    const ed = createEditor('<p>Hello world</p>')
+    ed.commands.setTextSelection(7)
+
+    applyLink(ed, form(), getLinkContext(ed))
+
+    expect(ed.getHTML()).toBe('<p>Hello <a href="https://example.com">https://example.com</a>world</p>')
+  })
+
+  it('sets only the mark when the selected text is unchanged', () => {
+    const ed = createEditor('<p>Hello world</p>')
+    ed.commands.setTextSelection({ from: 7, to: 12 })
+    const context = getLinkContext(ed)
+
+    expect(context.text).toBe('world')
+    applyLink(ed, form({ text: 'world', newTab: true, rel: ['nofollow'] }), context)
+
+    expect(ed.getHTML()).toBe(
+      '<p>Hello <a target="_blank" rel="nofollow noopener noreferrer" href="https://example.com">world</a></p>',
+    )
+  })
+
+  it('replaces the selection when the text is changed', () => {
+    const ed = createEditor('<p>Hello world</p>')
+    ed.commands.setTextSelection({ from: 7, to: 12 })
+    const context = getLinkContext(ed)
+
+    applyLink(ed, form({ text: 'there' }), context)
+
+    expect(ed.getHTML()).toBe('<p>Hello <a href="https://example.com">there</a></p>')
+  })
+
+  it('updates the attributes of the link under the caret, keeping the others', () => {
+    const ed = createEditor('<p>Go <a href="https://old.com" target="_blank" rel="noopener noreferrer" class="btn" title="Old">old site</a> now</p>')
+    ed.commands.setTextSelection(6)
+    const context = getLinkContext(ed)
+
+    expect(context.active).toBe(true)
+    expect(context.text).toBe('old site')
+    expect(context.attrs).toMatchObject({ href: 'https://old.com', target: '_blank', class: 'btn' })
+
+    applyLink(ed, form({ href: 'https://new.com', text: 'old site', newTab: false, rel: ['ugc'] }), context)
+
+    expect(ed.getHTML()).toBe('<p>Go <a rel="ugc" href="https://new.com" title="Old">old site</a> now</p>')
+  })
+
+  it('replaces the text of the edited link', () => {
+    const ed = createEditor('<p>Go <a href="https://old.com" title="Old">old site</a> now</p>')
+    ed.commands.setTextSelection(6)
+    const context = getLinkContext(ed)
+
+    applyLink(ed, form({ href: 'https://old.com', text: 'new site' }), context)
+
+    expect(ed.getHTML()).toBe('<p>Go <a href="https://old.com" title="Old">new site</a> now</p>')
+  })
+
+  it('removes the whole link under the caret', () => {
+    const ed = createEditor('<p>Go <a href="https://old.com">old site</a> now</p>')
+    ed.commands.setTextSelection(6)
+
+    expect(removeLink(ed)).toBe(true)
+    expect(ed.getHTML()).toBe('<p>Go old site now</p>')
+  })
+})
+
+describe('linkToCard', () => {
+  let editor: Editor | null = null
+
+  const card: LinkCardAttrs = {
+    href: 'https://example.com/page',
+    title: 'Page',
+    description: null,
+    image: null,
+    siteName: null,
+    layout: 'compact',
+    newTab: false,
+  }
+
+  function createEditor(content: string) {
+    editor = new Editor({
+      element: document.createElement('div'),
+      content,
+      extensions: [
+        Document,
+        Paragraph,
+        Text,
+        Link.configure({ openOnClick: false, enableClickSelection: true, defaultProtocol: 'https' }),
+        TiptapifyLink.configure({ openOnClick: false, defaultProtocol: 'https' }),
+        LinkCard,
+      ],
+    })
+
+    return editor
+  }
+
+  function types(ed: Editor): string[] {
+    const names: string[] = []
+    ed.state.doc.forEach(node => names.push(node.type.name))
+
+    return names
+  }
+
+  afterEach(() => {
+    editor?.destroy()
+    editor = null
+  })
+
+  it('replaces the paragraph of a link that is its whole text', () => {
+    const ed = createEditor('<p>Before</p><p><a href="https://example.com/page">Page</a></p><p>After</p>')
+    ed.commands.setTextSelection(11)
+
+    expect(linkToCard(ed, card, getLinkContext(ed))).toBe(true)
+
+    expect(types(ed)).toEqual(['paragraph', 'linkCard', 'paragraph'])
+    expect(ed.state.doc.child(1).attrs).toEqual(card)
+    expect(ed.getHTML()).not.toContain('<p></p>')
+  })
+
+  it('replaces only the link inside a longer text, splitting the paragraph', () => {
+    const ed = createEditor('<p>See <a href="https://example.com/page">Page</a> now</p>')
+    ed.commands.setTextSelection(7)
+
+    linkToCard(ed, card, getLinkContext(ed))
+
+    expect(types(ed)).toEqual(['paragraph', 'linkCard', 'paragraph'])
+    expect(ed.state.doc.child(0).textContent).toBe('See ')
+    expect(ed.state.doc.child(2).textContent).toBe(' now')
+  })
+
+  it('takes the place of an empty paragraph, or of the selection', () => {
+    const ed = createEditor('<p>One</p><p></p>')
+    ed.commands.setTextSelection(6)
+
+    linkToCard(ed, card, getLinkContext(ed))
+    expect(types(ed)).toEqual(['paragraph', 'linkCard'])
+
+    ed.commands.setContent('<p>Hello world</p>')
+    ed.commands.setTextSelection({ from: 1, to: 12 })
+    linkToCard(ed, card, getLinkContext(ed))
+    expect(types(ed)).toEqual(['linkCard'])
+  })
+})

package/src/extensions/components/media/link/linkDialog.ts

@@ -0,0 +1,154 @@
+import { Editor, getMarkRange } from '@tiptap/core'
+import { LinkCardAttrs } from '@tiptapify/extensions/components/media/linkCard'
+
+// Legacy `tiptapify_link` marks turn into this one as content loads (`migrateLegacyLinks` in ./index.ts)
+export const LINK_MARK = 'link'
+
+// Link types from the HTML spec, offered as suggestions; any other value is accepted too
+export const REL_SUGGESTIONS = [
+  'alternate', 'author', 'bookmark', 'external', 'help', 'license', 'me', 'next', 'nofollow', 'noopener',
+  'noreferrer', 'opener', 'prev', 'privacy-policy', 'search', 'sponsored', 'tag', 'ugc',
+]
+
+// Added automatically to a link that opens in a new tab
+export const NEW_TAB_REL = ['noopener', 'noreferrer']
+
+export interface LinkContext {
+  // A link is under the caret or selected: the dialog edits it
+  active: boolean
+  attrs: Record<string, unknown>
+  // Text of the link being edited, or of the selection
+  text: string
+}
+
+export interface LinkForm {
+  href: string
+  text: string
+  newTab: boolean
+  rel: string[]
+  cssClass: string
+}
+
+const schemeRegex = /^[a-z][a-z0-9+-]*:/i
+// A host with a dot (optionally a port), then a path, query, fragment or the end
+const hostRegex = /^[^\s/?#@:]+\.[^\s/?#@:.]+(:\d+)?([/?#]|$)/
+// A host with a port and no dot (`localhost:8080`): it looks like a scheme, but the digits are a port
+const hostPortRegex = /^[^\s/?#@:.]+:\d+([/?#]|$)/
+
+// Offered when an address has no protocol: the editor never picks one itself
+export const LINK_PROTOCOLS = ['https', 'http', 'ftp']
+
+/**
+ * An address of a host typed without a protocol (`example.com/page`, `internal.com:21`, `localhost:8080`):
+ * a browser can't open it, and only the author knows which protocol it is, so the dialog asks for one.
+ * Explicit protocols, anchors, relative paths and queries are complete
+ */
+export function missingProtocol(value: string): boolean {
+  const href = (value ?? '').trim()
+
+  return hostPortRegex.test(href) || (!schemeRegex.test(href) && hostRegex.test(href))
+}
+
+export function withProtocol(value: string, protocol: string): string {
+  return `${protocol}://${(value ?? '').trim()}`
+}
+
+/**
+ * Rel values from an attribute string or a list (chips, pasted text): split on spaces and commas,
+ * trimmed, lowercased, deduplicated
+ */
+export function parseRel(value: string | string[] | null | undefined): string[] {
+  const parts = Array.isArray(value) ? value : [value ?? '']
+  const values = parts.flatMap(part => String(part ?? '').split(/[\s,]+/))
+    .map(item => item.trim().toLowerCase())
+    .filter(Boolean)
+
+  return [...new Set(values)]
+}
+
+export function serializeRel(values: string[]): string | null {
+  const rel = parseRel(values)
+
+  return rel.length ? rel.join(' ') : null
+}
+
+export function withNewTabRel(rel: string[], newTab: boolean): string[] {
+  return newTab ? parseRel([...rel, ...NEW_TAB_REL]) : parseRel(rel)
+}
+
+// The values the form shows: those added automatically for a new tab are implied by the checkbox
+export function formRel(rel: string | null | undefined, newTab: boolean): string[] {
+  const values = parseRel(rel)
+
+  return newTab ? values.filter(item => !NEW_TAB_REL.includes(item)) : values
+}
+
+export function hasAdvancedValues(rel: string[], cssClass: string): boolean {
+  return rel.some(item => !NEW_TAB_REL.includes(item)) || cssClass.trim() !== ''
+}
+
+export function linkAttrs(form: LinkForm) {
+  return {
+    href: form.href.trim(),
+    target: form.newTab ? '_blank' : null,
+    rel: serializeRel(withNewTabRel(form.rel, form.newTab)),
+    class: form.cssClass.trim() || null,
+  }
+}
+
+export function getLinkContext(editor: Editor): LinkContext {
+  const { state } = editor
+  const { selection, doc } = state
+  const markType = state.schema.marks[LINK_MARK]
+  const range = markType && editor.isActive(LINK_MARK) ? getMarkRange(selection.$from, markType) : undefined
+
+  if (range) {
+    return { active: true, attrs: editor.getAttributes(LINK_MARK), text: doc.textBetween(range.from, range.to, ' ') }
+  }
+
+  return { active: false, attrs: {}, text: doc.textBetween(selection.from, selection.to, ' ') }
+}
+
+/**
+ * Sets the link on the selection or on the whole link being edited. A changed text (or no text
+ * to link) replaces the range with the text carrying the link; otherwise only the mark is set,
+ * which keeps the attributes the dialog does not know about (e.g. `title`)
+ */
+export function applyLink(editor: Editor, form: LinkForm, context: LinkContext): boolean {
+  const attrs = linkAttrs(form)
+  const replaceText = form.text !== context.text || (!context.active && editor.state.selection.empty)
+  const chain = editor.chain().focus().extendMarkRange(LINK_MARK).setMeta('preventAutolink', true)
+
+  if (!replaceText) {
+    return chain.setMark(LINK_MARK, attrs).run()
+  }
+
+  const text = form.text.trim() ? form.text : attrs.href
+
+  return chain
+    .insertContent({ type: 'text', text, marks: [{ type: LINK_MARK, attrs: { ...context.attrs, ...attrs } }] })
+    // The mark is inclusive: what is typed right after the new link must not extend it
+    .unsetMark(LINK_MARK)
+    .run()
+}
+
+export function removeLink(editor: Editor): boolean {
+  return editor.chain().focus().extendMarkRange(LINK_MARK).unsetMark(LINK_MARK).run()
+}
+
+/**
+ * The link being edited (or the selection, or the caret) replaced with a card of the link. A link that is
+ * the whole text of its paragraph takes the paragraph's place, as does a card made in an empty paragraph.
+ */
+export function linkToCard(editor: Editor, attrs: LinkCardAttrs, context: LinkContext): boolean {
+  const { state } = editor
+  const { $from } = state.selection
+  const markType = state.schema.marks[LINK_MARK]
+  const range = (context.active && markType ? getMarkRange($from, markType) : undefined)
+    ?? { from: state.selection.from, to: state.selection.to }
+  const wholeParagraph = $from.parent.type.name === 'paragraph' && $from.depth > 0
+    && range.from === $from.start() && range.to === $from.end()
+  const target = wholeParagraph ? { from: $from.before(), to: $from.after() } : range
+
+  return editor.chain().focus().insertContentAt(target, { type: 'linkCard', attrs }).run()
+}