tiptapify 0.3.5 → 0.4.1

package/src/composables/fakeUploadEndpoint.ts

@@ -0,0 +1,65 @@
+import { vi } from 'vitest'
+
+// Tests only
+
+export type FakeUploadRequest = {
+  method: string,
+  url: string,
+  headers: Record<string, string>,
+  body: FormData,
+}
+
+export type FakeUploadAnswer = { status: number, body: unknown }
+
+/**
+ * Replaces XMLHttpRequest with one that records each request and answers it on the next task: first half of
+ * the upload progress, then `answer(request)`. Restored by `vi.unstubAllGlobals()`.
+ */
+export function fakeUploadEndpoint(answer: (request: FakeUploadRequest) => FakeUploadAnswer): FakeUploadRequest[] {
+  const requests: FakeUploadRequest[] = []
+
+  class FakeXMLHttpRequest {
+    upload: { onprogress: ((event: { lengthComputable: boolean, loaded: number, total: number }) => void) | null } = { onprogress: null }
+    onload: (() => void) | null = null
+    onerror: (() => void) | null = null
+    onabort: (() => void) | null = null
+    status = 0
+    responseText = ''
+    private request: FakeUploadRequest = { method: '', url: '', headers: {}, body: new FormData() }
+    private aborted = false
+
+    open(method: string, url: string) {
+      Object.assign(this.request, { method, url })
+    }
+
+    setRequestHeader(name: string, value: string) {
+      this.request.headers[name] = value
+    }
+
+    send(body: FormData) {
+      this.request.body = body
+      requests.push(this.request)
+
+      setTimeout(() => {
+        if (this.aborted) {
+          return
+        }
+
+        this.upload.onprogress?.({ lengthComputable: true, loaded: 1, total: 2 })
+        const { status, body: response } = answer(this.request)
+        this.status = status
+        this.responseText = typeof response === 'string' ? response : JSON.stringify(response)
+        this.onload?.()
+      })
+    }
+
+    abort() {
+      this.aborted = true
+      this.onabort?.()
+    }
+  }
+
+  vi.stubGlobal('XMLHttpRequest', FakeXMLHttpRequest)
+
+  return requests
+}

package/src/composables/useTiptapifyConfig.ts

@@ -15,6 +15,24 @@ export interface TiptapifyConfig {
   // css variable name -> value; only overrides, the css fallbacks carry the base
   tokens: ComputedRef<Record<string, string>>
   shape: ComputedRef<Required<TiptapifyShape>>
+  // the skin and shape classes of the editor root
+  rootClasses: ComputedRef<string[]>
+}
+
+/**
+ * The classes of the editor root: the skin name class (the escape hatch for consumer CSS) and
+ * `tiptapify-shape-{flag}-{value}` for all six shape flags, which the skin CSS gates on.
+ */
+export function skinRootClasses(className: string, shape: Required<TiptapifyShape>): string[] {
+  return [
+    className,
+    `tiptapify-shape-toolbar-${shape.toolbar}`,
+    `tiptapify-shape-groups-${shape.groups}`,
+    `tiptapify-shape-buttons-${shape.buttons}`,
+    `tiptapify-shape-bubble-${shape.bubble}`,
+    `tiptapify-shape-dialog-${shape.dialog}`,
+    `tiptapify-shape-menu-${shape.menu}`,
+  ]
 }
 
 export const TIPTAPIFY_CONFIG_KEY: InjectionKey<TiptapifyConfig> = Symbol('tiptapifyConfig')
@@ -32,5 +50,6 @@ export function useTiptapifyConfig(): TiptapifyConfig {
     skinName: computed(() => defaultSkin.name),
     tokens: computed(() => defaultSkin.tokens),
     shape: computed(() => defaultSkin.shape),
+    rootClasses: computed(() => skinRootClasses(defaultSkin.className, defaultSkin.shape)),
   })
 }

package/src/composables/useTiptapifyLinkPreview.test.ts

@@ -0,0 +1,51 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { nextTick, ref } from 'vue'
+import { createLinkPreviewState } from '@tiptapify/composables/useTiptapifyLinkPreview'
+import { resetLinkPreviewChecks } from '@tiptapify/extensions/components/media/linkCard/linkPreview'
+import { TiptapifyLinkPreviewOptions } from '@tiptapify/types/editor'
+
+const flush = () => new Promise(resolve => setTimeout(resolve))
+
+describe('linkPreview prop', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+    resetLinkPreviewChecks()
+  })
+
+  it('makes link cards available once the endpoint answers the handshake', async () => {
+    vi.stubGlobal('fetch', vi.fn(() => Promise.resolve(new Response(JSON.stringify({ tiptapifyLinkPreview: 1 })))))
+
+    const { available } = createLinkPreviewState(ref({ endpoint: '/api/link-preview' }))
+    expect(available.value).toBe(false)
+
+    await flush()
+    expect(available.value).toBe(true)
+  })
+
+  it('keeps link cards off without an endpoint, and asks nothing', async () => {
+    const fetch = vi.fn()
+    vi.stubGlobal('fetch', fetch)
+
+    const { available } = createLinkPreviewState(ref(null))
+    await flush()
+
+    expect(available.value).toBe(false)
+    expect(fetch).not.toHaveBeenCalled()
+  })
+
+  it('checks a new endpoint when the prop changes', async () => {
+    vi.stubGlobal('fetch', vi.fn((url: string) => Promise.resolve(
+      new Response(url === '/ok' ? JSON.stringify({ tiptapifyLinkPreview: 1 }) : 'nope', { status: url === '/ok' ? 200 : 404 }),
+    )))
+    const options = ref<TiptapifyLinkPreviewOptions | null>({ endpoint: '/missing' })
+
+    const { available } = createLinkPreviewState(options)
+    await flush()
+    expect(available.value).toBe(false)
+
+    options.value = { endpoint: '/ok' }
+    await nextTick()
+    await flush()
+    expect(available.value).toBe(true)
+  })
+})

package/src/composables/useTiptapifyLinkPreview.ts

@@ -0,0 +1,60 @@
+import { InjectionKey, inject, ref, Ref, watch } from 'vue'
+import { checkLinkPreview, fetchLinkPreview } from '@tiptapify/extensions/components/media/linkCard/linkPreview'
+import { TiptapifyLinkPreviewData, TiptapifyLinkPreviewOptions } from '@tiptapify/types/editor'
+
+export type TiptapifyLinkPreviewState = {
+  options: Ref<TiptapifyLinkPreviewOptions | null>,
+  // The endpoint answered the handshake: link cards can be made
+  available: Ref<boolean>,
+}
+
+export const TIPTAPIFY_LINK_PREVIEW_KEY: InjectionKey<TiptapifyLinkPreviewState> = Symbol('tiptapifyLinkPreview')
+
+/**
+ * The `linkPreview` prop of the editor, checked by the handshake whenever its endpoint changes.
+ */
+export function createLinkPreviewState(options: Ref<TiptapifyLinkPreviewOptions | null>): TiptapifyLinkPreviewState {
+  const available = ref(false)
+
+  watch(() => options.value?.endpoint, async () => {
+    const current = options.value
+    available.value = false
+
+    if (current?.endpoint) {
+      const ok = await checkLinkPreview(current)
+      // An answer for an endpoint changed meanwhile is stale
+      if (options.value?.endpoint === current.endpoint) {
+        available.value = ok
+      }
+    }
+  }, { immediate: true })
+
+  return { options, available }
+}
+
+/**
+ * Link cards in the dialogs and the paste menu: whether they can be made, the data of a page, and a new
+ * handshake for an endpoint that failed (asked when the link dialog opens: it may be up by now).
+ */
+export function useTiptapifyLinkPreview(): {
+  available: Ref<boolean>,
+  fetchPreview: (url: string, signal?: AbortSignal) => Promise<TiptapifyLinkPreviewData>,
+  recheck: () => Promise<void>,
+} {
+  const { options, available } = inject(TIPTAPIFY_LINK_PREVIEW_KEY, { options: ref(null), available: ref(false) })
+
+  function fetchPreview(url: string, signal?: AbortSignal): Promise<TiptapifyLinkPreviewData> {
+    return options.value
+      ? fetchLinkPreview(options.value, url, signal)
+      : Promise.reject(new Error('The editor has no linkPreview endpoint'))
+  }
+
+  async function recheck(): Promise<void> {
+    const current = options.value
+    if (current?.endpoint && !available.value) {
+      available.value = await checkLinkPreview(current, { recheckFailed: true })
+    }
+  }
+
+  return { available, fetchPreview, recheck }
+}

package/src/composables/useTiptapifyUpload.test.ts

@@ -0,0 +1,96 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createApp, h, provide, ref } from 'vue'
+import { fakeUploadEndpoint } from '@tiptapify/composables/fakeUploadEndpoint'
+import { TIPTAPIFY_UPLOAD_KEY, useTiptapifyUpload } from '@tiptapify/composables/useTiptapifyUpload'
+import { TiptapifyUploadOptions } from '@tiptapify/types/editor'
+
+function withUpload(upload: TiptapifyUploadOptions | null) {
+  let result!: ReturnType<typeof useTiptapifyUpload>
+  const Probe = { setup: () => { result = useTiptapifyUpload(); return () => null } }
+  createApp({ setup: () => { provide(TIPTAPIFY_UPLOAD_KEY, ref(upload)); return () => h(Probe) } })
+    .mount(document.createElement('div'))
+
+  return result
+}
+
+const context = (kind: 'image' | 'video', onProgress = vi.fn(), signal = new AbortController().signal) => ({ kind, onProgress, signal })
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('useTiptapifyUpload', () => {
+  it('embeds an image as a base64 data URL when the editor has no upload endpoint', async () => {
+    const { canUploadImage, canUploadVideo, upload, uploadFile } = withUpload(null)
+    const onProgress = vi.fn()
+
+    const { url } = await uploadFile(new File(['hi'], 'a.png', { type: 'image/png' }), context('image', onProgress))
+
+    expect(canUploadImage.value).toBe(true)
+    expect(canUploadVideo.value).toBe(false)
+    expect(upload.value).toBeNull()
+    expect(url).toBe('data:image/png;base64,aGk=')
+    expect(onProgress).toHaveBeenLastCalledWith(1)
+  })
+
+  it('does not embed a video file: it needs the upload endpoint', async () => {
+    const { uploadFile } = withUpload(null)
+
+    await expect(uploadFile(new File(['v'], 'a.mp4', { type: 'video/mp4' }), context('video'))).rejects.toThrow()
+  })
+
+  it('stops reading the file when the upload is cancelled', async () => {
+    const { uploadFile } = withUpload(null)
+    const controller = new AbortController()
+    controller.abort()
+
+    await expect(uploadFile(new File(['hi'], 'a.png'), context('image', vi.fn(), controller.signal))).rejects.toThrow()
+  })
+
+  it('posts images and videos to the upload endpoint with its headers and gives the URL it answers', async () => {
+    const requests = fakeUploadEndpoint(() => ({ status: 201, body: { url: 'https://cdn.example.com/clip.mp4' } }))
+    const { canUploadVideo, upload, uploadFile } = withUpload({ endpoint: '/api/uploads', headers: { Authorization: 'Bearer t' } })
+    const file = new File(['v'], 'clip.mp4', { type: 'video/mp4' })
+    const onProgress = vi.fn()
+
+    expect(await uploadFile(file, context('video', onProgress))).toEqual({ url: 'https://cdn.example.com/clip.mp4' })
+
+    expect(canUploadVideo.value).toBe(true)
+    expect(upload.value).toBeTypeOf('function')
+    expect(requests).toHaveLength(1)
+    expect(requests[0]).toMatchObject({ method: 'POST', url: '/api/uploads', headers: { Accept: 'application/json', Authorization: 'Bearer t' } })
+    expect(requests[0].body.get('file')).toBeInstanceOf(File)
+    expect((requests[0].body.get('file') as File).name).toBe('clip.mp4')
+    expect(requests[0].body.get('kind')).toBe('video')
+    expect(onProgress.mock.calls).toEqual([[0.5], [1]])
+  })
+
+  it('rejects with the error the endpoint answers, or with an empty message and the status', async () => {
+    fakeUploadEndpoint(request => (request.body.get('kind') === 'image'
+      ? { status: 413, body: { error: 'The file is too large.' } }
+      : { status: 500, body: 'Internal Server Error' }))
+    const { uploadFile } = withUpload({ endpoint: '/api/uploads' })
+
+    await expect(uploadFile(new File(['hi'], 'a.png'), context('image'))).rejects.toThrow('The file is too large.')
+    await expect(uploadFile(new File(['v'], 'a.mp4'), context('video'))).rejects.toMatchObject({ message: '', status: 500 })
+  })
+
+  it('rejects an answer without a url', async () => {
+    fakeUploadEndpoint(() => ({ status: 200, body: { path: 'a.png' } }))
+    const { uploadFile } = withUpload({ endpoint: '/api/uploads' })
+
+    await expect(uploadFile(new File(['hi'], 'a.png'), context('image'))).rejects.toMatchObject({ message: '', status: 200 })
+  })
+
+  it('aborts the request when the upload is cancelled', async () => {
+    const requests = fakeUploadEndpoint(() => ({ status: 200, body: { url: '/a.png' } }))
+    const { uploadFile } = withUpload({ endpoint: '/api/uploads' })
+    const controller = new AbortController()
+
+    const pending = uploadFile(new File(['hi'], 'a.png'), context('image', vi.fn(), controller.signal))
+    controller.abort()
+
+    await expect(pending).rejects.toThrow('cancelled')
+    expect(requests).toHaveLength(1)
+  })
+})

package/src/composables/useTiptapifyUpload.ts

@@ -0,0 +1,126 @@
+import { computed, ComputedRef, inject, InjectionKey, Ref, ref } from 'vue'
+import { TiptapifyUpload, TiptapifyUploadContext, TiptapifyUploadOptions } from '@tiptapify/types/editor'
+
+export const TIPTAPIFY_UPLOAD_KEY: InjectionKey<Ref<TiptapifyUploadOptions | null>> = Symbol('tiptapifyUpload')
+
+function cancelled(): DOMException {
+  return new DOMException('The upload was cancelled', 'AbortError')
+}
+
+/**
+ * A picked image as a base64 data URL, for an editor without an upload endpoint.
+ */
+function readAsDataUrl(file: File, { onProgress, signal }: TiptapifyUploadContext): Promise<{ url: string }> {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(cancelled())
+
+      return
+    }
+
+    const reader = new FileReader()
+    reader.onprogress = event => event.lengthComputable && onProgress(event.loaded / event.total)
+    reader.onload = () => {
+      onProgress(1)
+      resolve({ url: String(reader.result) })
+    }
+    reader.onerror = () => reject(reader.error ?? new Error('The file could not be read'))
+    reader.onabort = () => reject(cancelled())
+    signal.addEventListener('abort', () => reader.abort(), { once: true })
+    reader.readAsDataURL(file)
+  })
+}
+
+function parseJson(text: string): Record<string, unknown> | null {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * XMLHttpRequest, not fetch: it reports the progress of the upload itself. A failure carries the endpoint's
+ * `error` as its message, else an empty one: the dialogs then show their own translated message.
+ */
+function sendToEndpoint(
+  { endpoint, headers }: TiptapifyUploadOptions,
+  file: File,
+  { kind, onProgress, signal }: TiptapifyUploadContext,
+): Promise<{ url: string }> {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(cancelled())
+
+      return
+    }
+
+    const request = new XMLHttpRequest()
+    request.open('POST', endpoint)
+    request.setRequestHeader('Accept', 'application/json')
+    for (const [name, value] of Object.entries(headers ?? {})) {
+      request.setRequestHeader(name, value)
+    }
+
+    request.upload.onprogress = event => event.lengthComputable && onProgress(event.loaded / event.total)
+    request.onload = () => {
+      const body = parseJson(request.responseText)
+      if (request.status >= 200 && request.status < 300 && typeof body?.url === 'string' && body.url) {
+        onProgress(1)
+        resolve({ url: body.url })
+
+        return
+      }
+
+      reject(Object.assign(new Error(typeof body?.error === 'string' ? body.error : ''), { status: request.status }))
+    }
+    request.onerror = () => reject(Object.assign(new Error(''), { status: 0 }))
+    request.onabort = () => reject(cancelled())
+    signal.addEventListener('abort', () => request.abort(), { once: true })
+
+    const form = new FormData()
+    form.append('file', file)
+    form.append('kind', kind)
+    request.send(form)
+  })
+}
+
+/**
+ * Files picked in the dialogs. With the `upload` endpoint of the editor they are sent to it and the document
+ * keeps their URL. Without it an image (a video poster, the image of a link card) is embedded as base64, and
+ * a video file can't be picked: a document would grow by its whole size.
+ */
+export function useTiptapifyUpload(): {
+  // null without an upload endpoint
+  upload: ComputedRef<TiptapifyUpload | null>,
+  canUploadImage: ComputedRef<boolean>,
+  canUploadVideo: ComputedRef<boolean>,
+  uploadFile: TiptapifyUpload,
+} {
+  const options = inject(TIPTAPIFY_UPLOAD_KEY, ref(null))
+
+  const upload = computed<TiptapifyUpload | null>(() => {
+    const current = options.value
+
+    return current?.endpoint ? (file, context) => sendToEndpoint(current, file, context) : null
+  })
+
+  function uploadFile(file: File, context: TiptapifyUploadContext): Promise<{ url: string }> {
+    if (upload.value) {
+      return upload.value(file, context)
+    }
+
+    if (context.kind === 'image') {
+      return readAsDataUrl(file, context)
+    }
+
+    return Promise.reject(new Error('A video file needs the upload endpoint of the editor'))
+  }
+
+  return {
+    upload,
+    canUploadImage: computed(() => true),
+    canUploadVideo: computed(() => upload.value !== null),
+    uploadFile,
+  }
+}