tiptapify 0.3.1 → 0.3.3

package/src/extensions/components/media/image/ImageDialog.vue

@@ -150,7 +150,7 @@ onUnmounted(() => {
             <VTextField
               v-model="attrs.title"
               density="comfortable"
-              :label="t('dialog.image.title')"
+              :label="t('dialog.image.caption')"
             />
           </div>
         </div>

package/src/extensions/components/media/image/caption.test.ts

@@ -0,0 +1,122 @@
+import { afterEach, describe, expect, it, vi } 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 { TiptapifyImage } from '@tiptapify/extensions/components/media/image'
+import { ImageWithCaption } from '@tiptapify/extensions/components/media/image/caption'
+
+let editor: Editor | null = null
+
+function createEditor(content: string) {
+  editor = new Editor({
+    element: document.createElement('div'),
+    content,
+    extensions: [
+      Document,
+      Paragraph,
+      Text,
+      TiptapifyImage,
+      ImageWithCaption.configure({
+        resize: { enabled: true, alwaysPreserveAspectRatio: true },
+        captionPlaceholder: 'Add a caption',
+      }),
+    ],
+  })
+
+  return editor
+}
+
+function caption(): HTMLInputElement {
+  return editor!.view.dom.querySelector('.tiptapify-image-caption') as HTMLInputElement
+}
+
+function typeCaption(value: string) {
+  caption().value = value
+  caption().dispatchEvent(new Event('input'))
+}
+
+describe('image caption', () => {
+  afterEach(() => {
+    editor?.destroy()
+    editor = null
+  })
+
+  it('shows the image title as the caption under the image', () => {
+    createEditor('<img src="https://example.com/a.png" title="Kyiv at night">')
+
+    expect(caption().value).toBe('Kyiv at night')
+    expect(caption().placeholder).toBe('Add a caption')
+  })
+
+  it('saves the typed caption as the figure caption', () => {
+    createEditor('<img src="https://example.com/a.png">')
+
+    typeCaption('Kyiv at night')
+
+    expect(editor!.getHTML()).toBe('<figure><img src="https://example.com/a.png"><figcaption>Kyiv at night</figcaption></figure>')
+  })
+
+  it('saves an image without a caption as a figure without figcaption', () => {
+    createEditor('<img src="https://example.com/a.png" title="Kyiv at night">')
+
+    typeCaption('  ')
+
+    expect(editor!.getHTML()).toBe('<figure><img src="https://example.com/a.png"></figure>')
+  })
+
+  it('loads a figure with its caption and image attributes', () => {
+    createEditor('<figure><img src="https://example.com/a.png" alt="Kyiv" width="640"><figcaption> Kyiv at night </figcaption></figure>')
+
+    expect(caption().value).toBe('Kyiv at night')
+    expect(editor!.getJSON().content![0].attrs).toMatchObject({ src: 'https://example.com/a.png', alt: 'Kyiv', width: 640, title: 'Kyiv at night' })
+  })
+
+  it('keeps consecutive figures as separate images', () => {
+    createEditor('<figure><img src="https://example.com/a.png"></figure><figure><img src="https://example.com/b.png"></figure>')
+
+    expect(editor!.getJSON().content!.map(node => node.type)).toEqual(['image', 'image'])
+  })
+
+  it('updates the caption when the title is changed elsewhere', () => {
+    createEditor('<img src="https://example.com/a.png">')
+
+    editor!.chain().setNodeSelection(0).updateAttributes('image', { title: 'From the dialog' }).run()
+
+    expect(caption().value).toBe('From the dialog')
+  })
+
+  it('opens the image dialog for this image on double click', () => {
+    createEditor('<p>text</p><img src="https://example.com/a.png" alt="Kyiv">')
+    const listener = vi.fn()
+    window.addEventListener('tiptapify-show-tiptapifyImage', listener)
+
+    editor!.view.dom.querySelector('[data-resize-wrapper]')!.dispatchEvent(new MouseEvent('dblclick', { bubbles: true }))
+
+    window.removeEventListener('tiptapify-show-tiptapifyImage', listener)
+    expect(listener).toHaveBeenCalledOnce()
+    expect(listener.mock.calls[0][0].detail.image).toMatchObject({ src: 'https://example.com/a.png', alt: 'Kyiv' })
+  })
+
+  it('moves the cursor to the text after the image on Enter', () => {
+    createEditor('<img src="https://example.com/a.png"><p>after</p>')
+
+    caption().dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }))
+
+    const { $from } = editor!.state.selection
+    expect($from.parent.textContent).toBe('after')
+  })
+
+  it('floats the image with the align attribute', () => {
+    createEditor('<img src="https://example.com/a.png" style="float: right">')
+    const nodeView = editor!.view.nodeDOM(0) as HTMLElement
+
+    expect(nodeView.dataset.align).toBe('right')
+    expect(editor!.getHTML()).toBe('<figure><img src="https://example.com/a.png" style="float: right;"></figure>')
+
+    editor!.chain().setNodeSelection(0).updateAttributes('image', { align: null }).run()
+
+    expect(nodeView.dataset.align).toBeUndefined()
+    expect(editor!.getHTML()).toBe('<figure><img src="https://example.com/a.png"></figure>')
+  })
+})

package/src/extensions/components/media/image/caption.ts

@@ -0,0 +1,268 @@
+import { Image, ImageOptions } from '@tiptap/extension-image'
+import { Editor, fromString, mergeAttributes, NodeViewRendererProps } from '@tiptap/core'
+import { Node as ProseMirrorNode } from '@tiptap/pm/model'
+import { NodeSelection, TextSelection } from '@tiptap/pm/state'
+
+export type ImageAlign = 'left' | 'right'
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    imageWithCaption: {
+      // Swaps the selected image with the image right before (-1) or after (1) it, as slides of a slider
+      moveImage: (direction: -1 | 1) => ReturnType
+    }
+  }
+}
+
+export interface ImageWithCaptionOptions extends ImageOptions {
+  captionPlaceholder: string
+}
+
+/**
+ * The image with its caption typed right under it, saved as
+ * `<figure><img src alt><figcaption>caption</figcaption></figure>`. In the document the caption is
+ * the image `title` attribute, so a legacy `<img title>` loads with its title as the caption.
+ * The image floats left or right with `align`, saved as `float` in the image style (what sites read
+ * from TinyMCE images); without it the image is centered. A double click opens the image dialog.
+ */
+export const ImageWithCaption = Image.extend<ImageWithCaptionOptions>({
+  addOptions() {
+    return {
+      ...this.parent?.() as ImageOptions,
+      captionPlaceholder: '',
+    }
+  },
+
+  addAttributes() {
+    return {
+      ...this.parent?.(),
+      align: {
+        default: null,
+        parseHTML: (element: HTMLElement) => (['left', 'right'].includes(element.style.float) ? element.style.float : null),
+        // Rendered by renderHTML onto the image only: in the editor the node view floats the whole figure
+        renderHTML: () => ({}),
+      },
+    }
+  },
+
+  parseHTML() {
+    const { editor, name, options } = this
+
+    return [
+      {
+        tag: 'figure',
+        getAttrs: (figure: HTMLElement) => {
+          const img = figure.querySelector('img[src]')
+          if (!img || (!options.allowBase64 && img.getAttribute('src')!.startsWith('data:'))) {
+            return false
+          }
+
+          const attrs = parseImageAttributes(editor as Editor, name, img as HTMLElement)
+          const caption = figure.querySelector('figcaption')?.textContent?.trim()
+
+          return { ...attrs, title: caption || attrs.title || null }
+        },
+      },
+      ...(this.parent?.() ?? []),
+    ]
+  },
+
+  renderHTML({ node, HTMLAttributes }) {
+    const align = node.attrs.align as ImageAlign | null
+    const { title, ...imageAttributes } = mergeAttributes(
+      this.options.HTMLAttributes,
+      HTMLAttributes,
+      align ? { style: `float: ${align}` } : {},
+    )
+    const figure: [string, Record<string, unknown>, ...unknown[]] = ['figure', {}, ['img', imageAttributes]]
+    if (title) {
+      figure.push(['figcaption', {}, String(title)])
+    }
+
+    return figure as never
+  },
+
+  addCommands() {
+    return {
+      ...this.parent?.(),
+      moveImage: (direction: -1 | 1) => ({ state, tr, dispatch }) => {
+        const { selection } = state
+        if (!(selection instanceof NodeSelection) || selection.node.type.name !== this.name) {
+          return false
+        }
+
+        const $image = state.doc.resolve(selection.from)
+        const siblingIndex = $image.index() + direction
+        if (siblingIndex < 0 || siblingIndex >= $image.parent.childCount) {
+          return false
+        }
+
+        const sibling = $image.parent.child(siblingIndex)
+        if (sibling.type !== selection.node.type) {
+          return false
+        }
+
+        if (dispatch) {
+          const image = selection.node
+          if (direction < 0) {
+            const from = selection.from - sibling.nodeSize
+            tr.replaceWith(from, selection.to, [image, sibling])
+            tr.setSelection(NodeSelection.create(tr.doc, from))
+          } else {
+            tr.replaceWith(selection.from, selection.to + sibling.nodeSize, [sibling, image])
+            tr.setSelection(NodeSelection.create(tr.doc, selection.from + sibling.nodeSize))
+          }
+          dispatch(tr.scrollIntoView())
+        }
+
+        return true
+      },
+    }
+  },
+
+  addNodeView() {
+    const createResizableView = this.parent?.()
+    if (!createResizableView) {
+      return null
+    }
+
+    const { captionPlaceholder } = this.options
+
+    return (props: NodeViewRendererProps) => {
+      const nodeView = createResizableView(props) as ReturnType<typeof createResizableView> & {
+        dom: HTMLElement
+        update: (node: ProseMirrorNode, ...args: unknown[]) => boolean
+        stopEvent?: (event: Event) => boolean
+        ignoreMutation?: (mutation: MutationRecord) => boolean
+      }
+      const editor = props.editor as Editor
+      const getPos = props.getPos as () => number | undefined
+      let node = props.node
+
+      const caption = document.createElement('input')
+      caption.type = 'text'
+      caption.className = 'tiptapify-image-caption'
+      caption.size = 1
+      caption.placeholder = captionPlaceholder
+      caption.value = node.attrs.title ?? ''
+      caption.disabled = !editor.isEditable
+
+
+      const wrapper = nodeView.dom.querySelector('[data-resize-wrapper]') ?? nodeView.dom
+      const syncAlign = (align: ImageAlign | null) => {
+        if (align) {
+          nodeView.dom.dataset.align = align
+        } else {
+          delete nodeView.dom.dataset.align
+        }
+      }
+      syncAlign(node.attrs.align)
+
+      // The aspect ratio lets CSS cap a tall image by its height without distorting it
+      const img = nodeView.dom.querySelector('img') as HTMLImageElement
+      const setAspectRatio = () => {
+        if (img.naturalWidth && img.naturalHeight) {
+          nodeView.dom.style.setProperty('--tiptapify-image-ratio', String(img.naturalWidth / img.naturalHeight))
+        }
+      }
+      img.addEventListener('load', setAspectRatio)
+      setAspectRatio()
+      nodeView.dom.classList.add('tiptapify-image')
+      nodeView.dom.append(caption)
+
+      const openDialog = () => {
+        const pos = getPos()
+        if (pos === undefined) {
+          return
+        }
+
+        // The dialog reads the selected image, so the selection must be applied before it opens
+        editor.commands.setNodeSelection(pos)
+        editor.commands.showTiptapifyImage()
+      }
+
+      const saveCaption = () => {
+        const pos = getPos()
+        const title = caption.value.trim() === '' ? null : caption.value
+        if (pos === undefined || title === (node.attrs.title ?? null)) {
+          return
+        }
+
+        editor.view.dispatch(editor.state.tr.setNodeAttribute(pos, 'title', title))
+      }
+
+      // Enter leaves the caption for the text after the image
+      const leaveCaption = () => {
+        const pos = getPos()
+        if (pos === undefined) {
+          return
+        }
+
+        const after = pos + node.nodeSize
+        const { state } = editor
+        const selection = TextSelection.near(state.doc.resolve(Math.min(after, state.doc.content.size)))
+        editor.view.dispatch(state.tr.setSelection(selection))
+        editor.view.focus()
+      }
+
+      caption.addEventListener('input', saveCaption)
+      caption.addEventListener('keydown', (event: KeyboardEvent) => {
+        if (event.key === 'Enter' || event.key === 'Escape') {
+          event.preventDefault()
+          leaveCaption()
+        }
+      })
+      // Selecting caption text with the mouse must not start dragging the whole image
+      caption.addEventListener('mousedown', () => {
+        nodeView.dom.draggable = false
+      })
+      caption.addEventListener('blur', () => {
+        nodeView.dom.draggable = true
+      })
+
+      wrapper.addEventListener('dblclick', openDialog)
+
+      const updateResizableView = nodeView.update.bind(nodeView)
+      nodeView.update = (updatedNode: ProseMirrorNode, ...args: unknown[]) => {
+        const updated = updateResizableView(updatedNode, ...args)
+        if (updated) {
+          node = updatedNode
+          const title = updatedNode.attrs.title ?? ''
+          if (caption.value !== title && document.activeElement !== caption) {
+            caption.value = title
+          }
+          caption.disabled = !editor.isEditable
+          syncAlign(updatedNode.attrs.align)
+        }
+
+        return updated
+      }
+      nodeView.stopEvent = (event: Event) => caption.contains(event.target as Node)
+      nodeView.ignoreMutation = (mutation: MutationRecord) => caption.contains(mutation.target)
+        || (mutation.type === 'attributes' && mutation.target === nodeView.dom)
+
+      return nodeView
+    }
+  },
+})
+
+/**
+ * The image attributes of a `<figure>` are read from its `<img>`, each one the way its extension
+ * reads it from an `<img>` (global attributes such as a media id included).
+ */
+function parseImageAttributes(editor: Editor, typeName: string, img: HTMLElement): Record<string, unknown> {
+  const attributes: Record<string, unknown> = {}
+
+  for (const { type, name, attribute } of editor.extensionManager.attributes) {
+    if (type !== typeName) {
+      continue
+    }
+
+    const value = attribute.parseHTML ? attribute.parseHTML(img) : fromString(img.getAttribute(name))
+    if (value !== null && value !== undefined) {
+      attributes[name] = value
+    }
+  }
+
+  return attributes
+}

package/src/extensions/components/media/image/slider.test.ts

@@ -0,0 +1,106 @@
+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 { Gapcursor } from '@tiptap/extensions'
+import { TiptapifyImage } from '@tiptapify/extensions/components/media/image'
+import { ImageWithCaption } from '@tiptapify/extensions/components/media/image/caption'
+import { findImageRuns, ImageSlider } from '@tiptapify/extensions/components/media/image/slider'
+
+let editor: Editor | null = null
+
+function createEditor(content: string, minImages = 3) {
+  editor = new Editor({
+    element: document.createElement('div'),
+    content,
+    extensions: [
+      Document,
+      Paragraph,
+      Text,
+      Gapcursor,
+      TiptapifyImage,
+      ImageWithCaption.configure({ resize: { enabled: true, alwaysPreserveAspectRatio: true } }),
+      ImageSlider.configure({ minImages, label: 'Slider' }),
+    ],
+  })
+
+  return editor
+}
+
+const img = (name: string) => `<img src="https://example.com/${name}.png">`
+
+function slideLabels(): Array<string | null> {
+  return [...editor!.view.dom.querySelectorAll('.tiptapify-image')]
+    .map(image => (image.classList.contains('tiptapify-slide') ? image.getAttribute('data-slide-label') : null))
+}
+
+describe('image slider', () => {
+  afterEach(() => {
+    editor?.destroy()
+    editor = null
+  })
+
+  it('finds runs of images with nothing between them', () => {
+    createEditor(`${img('a')}${img('b')}${img('c')}<p>text</p>${img('d')}${img('e')}`)
+
+    expect(findImageRuns(editor!.state.doc, 'image', 2).map(run => run.length)).toEqual([3, 2])
+    expect(findImageRuns(editor!.state.doc, 'image', 3).map(run => run.length)).toEqual([3])
+  })
+
+  it('numbers the slides of a run that reaches the minimum', () => {
+    createEditor(`<p>text</p>${img('a')}${img('b')}${img('c')}${img('d')}<p>text</p>${img('e')}${img('f')}`)
+
+    expect(slideLabels()).toEqual(['Slider · 1/4', '2', '3', '4', null, null])
+  })
+
+  it('uses the configured minimum', () => {
+    createEditor(`${img('a')}${img('b')}<p>text</p>${img('c')}`, 2)
+
+    expect(slideLabels()).toEqual(['Slider · 1/2', '2', null])
+  })
+
+  it('stops the slider when text splits the run', () => {
+    createEditor(`${img('a')}${img('b')}${img('c')}`)
+    editor!.chain().insertContentAt(editor!.state.doc.child(0).nodeSize, '<p>text</p>').run()
+
+    expect(slideLabels()).toEqual([null, null, null])
+  })
+
+  it('keeps the slides while an image is selected', () => {
+    createEditor(`${img('a')}${img('b')}${img('c')}`)
+    editor!.commands.setNodeSelection(0)
+    editor!.commands.focus()
+
+    expect(slideLabels()).toEqual(['Slider · 1/3', '2', '3'])
+  })
+
+  it('does nothing when the minimum is below two', () => {
+    createEditor(`${img('a')}${img('b')}${img('c')}`, 0)
+
+    expect(slideLabels()).toEqual([null, null, null])
+  })
+
+  it('swaps a slide with the next and the previous one', () => {
+    createEditor(`${img('a')}${img('b')}${img('c')}`)
+    const sources = () => editor!.getJSON().content!.map(node => node.attrs!.src.slice(-5))
+
+    editor!.commands.setNodeSelection(0)
+    expect(editor!.commands.moveImage(1)).toBe(true)
+    expect(sources()).toEqual(['b.png', 'a.png', 'c.png'])
+    expect(editor!.getAttributes('image').src).toContain('a.png')
+
+    expect(editor!.commands.moveImage(-1)).toBe(true)
+    expect(sources()).toEqual(['a.png', 'b.png', 'c.png'])
+  })
+
+  it('does not move an image past the end of its run', () => {
+    createEditor(`<p>text</p>${img('a')}${img('b')}`)
+    const first = editor!.state.doc.child(0).nodeSize
+
+    editor!.commands.setNodeSelection(first)
+
+    expect(editor!.can().moveImage(-1)).toBe(false)
+    expect(editor!.can().moveImage(1)).toBe(true)
+  })
+})

package/src/extensions/components/media/image/slider.ts

@@ -0,0 +1,87 @@
+import { Extension } from '@tiptap/core'
+import { Node as ProseMirrorNode } from '@tiptap/pm/model'
+import { Plugin, PluginKey } from '@tiptap/pm/state'
+import { Decoration, DecorationSet } from '@tiptap/pm/view'
+
+export interface ImageSliderOptions {
+  // How many images in a row make a slider; below 2 the extension does nothing
+  minImages: number
+  label: string
+}
+
+export type ImageRun = Array<{ from: number, to: number }>
+
+const name = 'tiptapifyImageSlider'
+
+/**
+ * Runs of at least `minImages` top-level images with nothing between them.
+ */
+export function findImageRuns(doc: ProseMirrorNode, typeName: string, minImages: number): ImageRun[] {
+  const runs: ImageRun[] = []
+  let run: ImageRun = []
+
+  const flush = () => {
+    if (run.length >= minImages) {
+      runs.push(run)
+    }
+    run = []
+  }
+
+  doc.forEach((node, offset) => {
+    if (node.type.name !== typeName) {
+      flush()
+
+      return
+    }
+
+    run.push({ from: offset, to: offset + node.nodeSize })
+  })
+  flush()
+
+  return runs
+}
+
+/**
+ * Images in a row that a site shows as a slider: the editor lays them out as a numbered grid
+ * (the `tiptapify-slide` classes) so the author sees the slider while writing.
+ */
+export const ImageSlider = Extension.create<ImageSliderOptions>({
+  name,
+
+  addOptions() {
+    return {
+      minImages: 0,
+      label: 'Slider',
+    }
+  },
+
+  addProseMirrorPlugins() {
+    const { minImages, label } = this.options
+    if (minImages < 2) {
+      return []
+    }
+
+    const decorate = (doc: ProseMirrorNode) => DecorationSet.create(
+      doc,
+      findImageRuns(doc, 'image', minImages).flatMap(run => run.map(({ from, to }, index) => Decoration.node(from, to, {
+        class: index === 0 ? 'tiptapify-slide tiptapify-slide--first' : 'tiptapify-slide',
+        'data-slide-label': index === 0 ? `${label} · 1/${run.length}` : String(index + 1),
+      }))),
+    )
+
+    return [
+      new Plugin({
+        key: new PluginKey(name),
+        state: {
+          init: (_, { doc }) => decorate(doc),
+          apply: (tr, decorations) => (tr.docChanged ? decorate(tr.doc) : decorations),
+        },
+        props: {
+          decorations(state) {
+            return this.getState(state)
+          },
+        },
+      }),
+    ]
+  },
+})