@puredesktop/platform-editor 1.0.0-beta.1

package/src/extensions/collectionImage.ts

@@ -0,0 +1,26 @@
+import Image from '@tiptap/extension-image'
+import { COLLECTION_ASSET_SRC_ATTR } from '../collectionAssetSrc.js'
+
+/**
+ * Collection document images: data URLs in the editor, relative `assets/…` paths on save
+ * via {@link COLLECTION_ASSET_SRC_ATTR} (see platform-ui `normalizeCollectionDocumentHtml`).
+ */
+export const CollectionImage = Image.extend({
+  addAttributes() {
+    return {
+      ...this.parent?.(),
+      collectionAssetSrc: {
+        default: null,
+        parseHTML: element => element.getAttribute(COLLECTION_ASSET_SRC_ATTR),
+        renderHTML: attributes => {
+          const stored = attributes.collectionAssetSrc
+          if (!stored || typeof stored !== 'string') return {}
+          return { [COLLECTION_ASSET_SRC_ATTR]: stored }
+        },
+      },
+    }
+  },
+}).configure({
+  inline: false,
+  allowBase64: true,
+})

package/src/extensions/collectionImagePaste.ts

@@ -0,0 +1,215 @@
+import { Extension } from '@tiptap/core'
+import { Plugin, PluginKey } from '@tiptap/pm/state'
+
+const SUPPORTED_MIME = new Set([
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/webp',
+  'image/svg+xml',
+])
+
+const EXT_FOR_MIME: Record<string, string> = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+  'image/svg+xml': 'svg',
+}
+
+export interface CollectionImagePastePayload {
+  name: string
+  bytes: Uint8Array
+  mimeType: string
+}
+
+export interface CollectionImagePasteExtensionOptions {
+  onError?: (message: string) => void
+  handleImage: (payload: CollectionImagePastePayload) => Promise<void>
+  /** Read bytes from an absolute path (external file:// drops). */
+  readBinary?: (absolutePath: string) => Promise<Uint8Array>
+}
+
+function normalizeMimeType(
+  mimeType: string | undefined,
+  name: string,
+): string | undefined {
+  const trimmed = mimeType?.trim().toLowerCase()
+  if (trimmed && SUPPORTED_MIME.has(trimmed)) return trimmed
+  const ext = name.split('.').pop()?.toLowerCase()
+  if (ext === 'png') return 'image/png'
+  if (ext === 'jpg' || ext === 'jpeg') return 'image/jpeg'
+  if (ext === 'gif') return 'image/gif'
+  if (ext === 'webp') return 'image/webp'
+  if (ext === 'svg') return 'image/svg+xml'
+  return undefined
+}
+
+function decodeDataImage(dataUrl: string): CollectionImagePastePayload {
+  const match = dataUrl.match(/^data:(image\/[a-z0-9.+-]+);base64,(.+)$/i)
+  if (!match) throw new Error('Unsupported data URL format.')
+  const [, mimeType, payload] = match
+  const binary = atob(payload)
+  const bytes = Uint8Array.from(binary, char => char.charCodeAt(0))
+  return {
+    bytes,
+    mimeType: mimeType.toLowerCase(),
+    name: `image.${EXT_FOR_MIME[mimeType.toLowerCase()] ?? 'png'}`,
+  }
+}
+
+function isSupportedImageFile(file: File): boolean {
+  return Boolean(normalizeMimeType(file.type, file.name))
+}
+
+function collectImageFiles(dt: DataTransfer): File[] {
+  const seen = new Set<File>()
+  const add = (file: File | null) => {
+    if (file && isSupportedImageFile(file)) seen.add(file)
+  }
+  for (const file of Array.from(dt.files)) add(file)
+  for (const item of Array.from(dt.items)) {
+    if (item.kind === 'file') add(item.getAsFile())
+  }
+  return [...seen]
+}
+
+function filePathFromDataTransfer(dt: DataTransfer): string | null {
+  const uri =
+    dt
+      .getData('text/uri-list')
+      ?.split('\n')
+      .map(line => line.trim())
+      .find(line => line && !line.startsWith('#')) ?? null
+  if (!uri) return null
+  try {
+    if (uri.startsWith('file://')) {
+      return decodeURIComponent(new URL(uri).pathname)
+    }
+    if (uri.startsWith('/')) return uri
+  } catch {
+    return null
+  }
+  return null
+}
+
+function nameFromLocalPath(filePath: string): string {
+  const normalized = filePath.replace(/\\/g, '/')
+  return normalized.split('/').pop() || 'image.png'
+}
+
+/** TipTap paste/drop hook — persistence is injected via `handleImage`. */
+export function createCollectionImagePasteExtension(
+  options: CollectionImagePasteExtensionOptions,
+): Extension {
+  const { onError, handleImage, readBinary } = options
+
+  return Extension.create({
+    name: 'collectionImagePaste',
+
+    addProseMirrorPlugins() {
+      const handleFiles = async (files: File[]): Promise<boolean> => {
+        const images = files.filter(isSupportedImageFile)
+        if (images.length === 0) {
+          if (files.length > 0) {
+            onError?.(
+              'Unsupported file type. Supported: PNG, JPEG, GIF, WebP, SVG.',
+            )
+          }
+          return false
+        }
+        for (const file of images) {
+          try {
+            await handleImage({
+              name: file.name,
+              bytes: new Uint8Array(await file.arrayBuffer()),
+              mimeType: normalizeMimeType(file.type, file.name) ?? 'image/png',
+            })
+          } catch (error) {
+            const message =
+              error instanceof Error ? error.message : String(error)
+            onError?.(`Could not save image: ${message}`)
+          }
+        }
+        return true
+      }
+
+      const handleExternalFilePath = async (
+        absolutePath: string,
+      ): Promise<boolean> => {
+        if (!readBinary) return false
+        const lower = absolutePath.toLowerCase()
+        if (!/\.(png|jpe?g|gif|webp|svg)$/.test(lower)) return false
+        try {
+          const bytes = await readBinary(absolutePath)
+          await handleImage({
+            name: nameFromLocalPath(absolutePath),
+            bytes,
+            mimeType: normalizeMimeType(undefined, absolutePath) ?? 'image/png',
+          })
+          return true
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error)
+          onError?.(`Could not import image: ${message}`)
+          return false
+        }
+      }
+
+      return [
+        new Plugin({
+          key: new PluginKey('collectionImagePaste'),
+          props: {
+            handlePaste(_view, event) {
+              const dt = event.clipboardData
+              if (!dt) return false
+
+              const files = collectImageFiles(dt)
+              if (files.length > 0) {
+                event.preventDefault()
+                void handleFiles(files)
+                return true
+              }
+
+              const text = dt.getData('text/plain')?.trim()
+              if (text?.startsWith('data:image/')) {
+                event.preventDefault()
+                void (async () => {
+                  try {
+                    await handleImage(decodeDataImage(text))
+                  } catch (error) {
+                    const message =
+                      error instanceof Error ? error.message : String(error)
+                    onError?.(`Could not save image: ${message}`)
+                  }
+                })()
+                return true
+              }
+
+              return false
+            },
+            handleDrop(_view, event) {
+              const dt = event.dataTransfer
+              if (!dt) return false
+
+              const files = collectImageFiles(dt)
+              if (files.length > 0) {
+                event.preventDefault()
+                void handleFiles(files)
+                return true
+              }
+
+              const externalPath = filePathFromDataTransfer(dt)
+              if (externalPath) {
+                event.preventDefault()
+                void handleExternalFilePath(externalPath)
+                return true
+              }
+
+              return false
+            },
+          },
+        }),
+      ]
+    },
+  })
+}

package/src/extensions/commentMark.ts

@@ -0,0 +1,223 @@
+import { Mark, mergeAttributes } from '@tiptap/core'
+import {
+  normalizeCommentReviewStatus,
+  normalizeCommentSeverity,
+  normalizeCommentType,
+  type CommentReviewStatus,
+  type CommentSeverity,
+  type CommentType,
+} from '../commentUtils.js'
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    commentMark: {
+      setCommentMark: (attrs: {
+        commentId: string
+        commentText: string
+        author?: string
+        createdAt?: string
+        commentType?: CommentType
+        subjectText?: string
+        reviewStatus?: CommentReviewStatus
+        severity?: CommentSeverity
+        replies?: string
+        resolvedAt?: string
+        resolvedBy?: string
+      }) => ReturnType
+      unsetCommentMark: () => ReturnType
+    }
+  }
+}
+
+export const CommentMark = Mark.create({
+  name: 'commentMark',
+  inclusive: false,
+  excludes: '',
+
+  addAttributes() {
+    return {
+      commentId: {
+        default: null,
+        parseHTML: el => el.getAttribute('data-comment-id'),
+        renderHTML: (attrs: { commentId?: string }) =>
+          attrs.commentId ? { 'data-comment-id': attrs.commentId } : {},
+      },
+      commentText: {
+        default: null,
+        parseHTML: el => el.getAttribute('data-comment-text'),
+        renderHTML: (attrs: { commentText?: string }) =>
+          attrs.commentText ? { 'data-comment-text': attrs.commentText } : {},
+      },
+      author: {
+        default: null,
+        parseHTML: el => el.getAttribute('data-comment-author'),
+        renderHTML: (attrs: { author?: string }) =>
+          attrs.author ? { 'data-comment-author': attrs.author } : {},
+      },
+      createdAt: {
+        default: null,
+        parseHTML: el => el.getAttribute('data-comment-created-at'),
+        renderHTML: (attrs: { createdAt?: string }) =>
+          attrs.createdAt ? { 'data-comment-created-at': attrs.createdAt } : {},
+      },
+      commentType: {
+        default: 'general',
+        parseHTML: el =>
+          normalizeCommentType(el.getAttribute('data-comment-type')),
+        renderHTML: (attrs: { commentType?: string }) => ({
+          'data-comment-type': normalizeCommentType(attrs.commentType),
+        }),
+      },
+      subjectText: {
+        default: null,
+        parseHTML: el => el.getAttribute('data-comment-subject'),
+        renderHTML: (attrs: { subjectText?: string }) =>
+          attrs.subjectText ? { 'data-comment-subject': attrs.subjectText } : {},
+      },
+      reviewStatus: {
+        default: null,
+        parseHTML: el => {
+          const type = normalizeCommentType(el.getAttribute('data-comment-type'))
+          return normalizeCommentReviewStatus(
+            el.getAttribute('data-comment-review-status'),
+            type,
+          )
+        },
+        renderHTML: (attrs: {
+          commentType?: string
+          reviewStatus?: string
+        }) => {
+          const type = normalizeCommentType(attrs.commentType)
+          const status =
+            attrs.reviewStatus ??
+            normalizeCommentReviewStatus(undefined, type)
+          return { 'data-comment-review-status': status }
+        },
+      },
+      severity: {
+        default: null,
+        parseHTML: el => {
+          const type = normalizeCommentType(el.getAttribute('data-comment-type'))
+          return normalizeCommentSeverity(
+            el.getAttribute('data-comment-severity'),
+            type,
+          )
+        },
+        renderHTML: (attrs: { commentType?: string; severity?: string }) => {
+          const type = normalizeCommentType(attrs.commentType)
+          const severity =
+            attrs.severity ?? normalizeCommentSeverity(undefined, type)
+          return { 'data-comment-severity': severity }
+        },
+      },
+      replies: {
+        default: null,
+        parseHTML: el => el.getAttribute('data-comment-replies'),
+        renderHTML: (attrs: { replies?: string }) =>
+          attrs.replies ? { 'data-comment-replies': attrs.replies } : {},
+      },
+      resolvedAt: {
+        default: null,
+        parseHTML: el => el.getAttribute('data-comment-resolved-at'),
+        renderHTML: (attrs: { resolvedAt?: string }) =>
+          attrs.resolvedAt
+            ? { 'data-comment-resolved-at': attrs.resolvedAt }
+            : {},
+      },
+      resolvedBy: {
+        default: null,
+        parseHTML: el => el.getAttribute('data-comment-resolved-by'),
+        renderHTML: (attrs: { resolvedBy?: string }) =>
+          attrs.resolvedBy
+            ? { 'data-comment-resolved-by': attrs.resolvedBy }
+            : {},
+      },
+    }
+  },
+
+  parseHTML() {
+    return [
+      {
+        tag: 'span[data-comment-id]',
+        getAttrs: el => ({
+          commentId: (el as HTMLElement).getAttribute('data-comment-id'),
+          commentText: (el as HTMLElement).getAttribute('data-comment-text'),
+          author: (el as HTMLElement).getAttribute('data-comment-author'),
+          createdAt: (el as HTMLElement).getAttribute(
+            'data-comment-created-at',
+          ),
+          commentType: normalizeCommentType(
+            (el as HTMLElement).getAttribute('data-comment-type'),
+          ),
+          subjectText: (el as HTMLElement).getAttribute(
+            'data-comment-subject',
+          ),
+          reviewStatus: normalizeCommentReviewStatus(
+            (el as HTMLElement).getAttribute('data-comment-review-status'),
+            normalizeCommentType(
+              (el as HTMLElement).getAttribute('data-comment-type'),
+            ),
+          ),
+          severity: normalizeCommentSeverity(
+            (el as HTMLElement).getAttribute('data-comment-severity'),
+            normalizeCommentType(
+              (el as HTMLElement).getAttribute('data-comment-type'),
+            ),
+          ),
+          replies: (el as HTMLElement).getAttribute('data-comment-replies'),
+          resolvedAt: (el as HTMLElement).getAttribute(
+            'data-comment-resolved-at',
+          ),
+          resolvedBy: (el as HTMLElement).getAttribute(
+            'data-comment-resolved-by',
+          ),
+        }),
+      },
+    ]
+  },
+
+  renderHTML({ HTMLAttributes, mark }) {
+    const attrs = mark.attrs as {
+      commentText?: string
+      author?: string
+      commentType?: string
+      resolvedAt?: string
+      reviewStatus?: string
+      severity?: string
+    }
+    const commentType = normalizeCommentType(attrs.commentType)
+    const title = attrs.author
+      ? `${attrs.author}: ${attrs.commentText ?? ''}`
+      : attrs.commentText ?? ''
+    return [
+      'span',
+      mergeAttributes(HTMLAttributes, {
+        class: [
+          'comment-mark',
+          `comment-mark--${commentType}`,
+          attrs.resolvedAt ? 'comment-mark--resolved' : '',
+        ]
+          .filter(Boolean)
+          .join(' '),
+        title,
+      }),
+      0,
+    ]
+  },
+
+  addCommands() {
+    return {
+      setCommentMark:
+        attrs =>
+        ({ commands, state }) => {
+          const { from, to } = state.selection
+          if (from === to) return false
+          return commands.setMark(this.name, attrs)
+        },
+      unsetCommentMark:
+        () =>
+        ({ commands }) =>
+          commands.unsetMark(this.name),
+    }
+  },
+})

package/src/extensions/documentAssetIdentity.ts

@@ -0,0 +1,54 @@
+import { Extension } from '@tiptap/core'
+import { Plugin } from '@tiptap/pm/state'
+
+const ASSET_NODE_TYPES = new Set(['table', 'inlineMath', 'blockMath'])
+
+function createDocumentAssetId(kind: string): string {
+  const id =
+    globalThis.crypto?.randomUUID?.() ?? Math.random().toString(36).slice(2)
+  return `asset_${kind}_${id}`
+}
+
+export const DocumentAssetIdentity = Extension.create({
+  name: 'documentAssetIdentity',
+
+  addGlobalAttributes() {
+    return [
+      {
+        types: [...ASSET_NODE_TYPES],
+        attributes: {
+          assetId: {
+            default: null,
+            parseHTML: element =>
+              element.getAttribute('data-asset-id')?.trim() || null,
+            renderHTML: attributes => {
+              const assetId = String(attributes.assetId ?? '').trim()
+              return assetId ? { 'data-asset-id': assetId } : {}
+            },
+          },
+        },
+      },
+    ]
+  },
+
+  addProseMirrorPlugins() {
+    return [
+      new Plugin({
+        appendTransaction: (_transactions, _oldState, newState) => {
+          let tr = newState.tr
+          let changed = false
+          newState.doc.descendants((node, pos) => {
+            if (!ASSET_NODE_TYPES.has(node.type.name)) return
+            if (node.attrs.assetId) return
+            tr = tr.setNodeMarkup(pos, undefined, {
+              ...node.attrs,
+              assetId: createDocumentAssetId(node.type.name),
+            })
+            changed = true
+          })
+          return changed ? tr : null
+        },
+      }),
+    ]
+  },
+})

package/src/extensions/figure.ts

@@ -0,0 +1,92 @@
+import { Node, mergeAttributes } from '@tiptap/core'
+
+export interface FigureOptions {
+  HTMLAttributes: Record<string, unknown>
+}
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    figure: {
+      /** Insert a figure block with an image and an editable caption. */
+      insertFigure: (opts: {
+        src: string
+        alt?: string
+        caption?: string
+      }) => ReturnType
+    }
+  }
+}
+
+/**
+ * Figure block — wraps an image and an editable caption. Markdown
+ * round-trip is via `![caption](src)` (CommonMark image syntax). The
+ * book's render pipeline already wraps such images in
+ * `<figure><img/><figcaption/></figure>` for PDF output, so the
+ * caption survives end-to-end even though it serializes through the
+ * standard image syntax.
+ *
+ * Image-only nodes (no caption) are still produced by Image nodes directly
+ * for inline images that don't deserve a figure wrapper.
+ */
+export const Figure = Node.create<FigureOptions>({
+  name: 'figure',
+  group: 'block',
+  content: 'inline*',
+  defining: true,
+  isolating: true,
+  draggable: true,
+
+  addOptions() {
+    return { HTMLAttributes: {} }
+  },
+
+  addAttributes() {
+    return {
+      src: {
+        default: null,
+        parseHTML: el => el.querySelector('img')?.getAttribute('src') ?? null,
+      },
+      alt: {
+        default: '',
+        parseHTML: el => el.querySelector('img')?.getAttribute('alt') ?? '',
+      },
+    }
+  },
+
+  parseHTML() {
+    return [
+      {
+        tag: 'figure',
+        getAttrs: element =>
+          element instanceof HTMLElement &&
+          element.getAttribute('data-type') === 'mermaid'
+            ? false
+            : null,
+        contentElement: 'figcaption',
+      },
+    ]
+  },
+
+  renderHTML({ node, HTMLAttributes }) {
+    const { src, alt } = node.attrs as { src: string | null; alt: string }
+    return [
+      'figure',
+      mergeAttributes(this.options.HTMLAttributes, HTMLAttributes),
+      ['img', { src, alt }],
+      ['figcaption', {}, 0],
+    ]
+  },
+
+  addCommands() {
+    return {
+      insertFigure:
+        ({ src, alt = '', caption = '' }) =>
+        ({ commands }) =>
+          commands.insertContent({
+            type: this.name,
+            attrs: { src, alt },
+            content: caption ? [{ type: 'text', text: caption }] : [],
+          }),
+    }
+  },
+})