@open-mercato/documents 0.6.8-develop.7016.1.4ed7b1e49d

package/src/modules/documents/backend/documents/[id]/useDocumentComments.ts

@@ -0,0 +1,286 @@
+"use client"
+
+import * as React from 'react'
+import type { Editor } from '@tiptap/core'
+import { apiCall, apiCallOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import {
+  DOCUMENTS_COMMENT_LIST_PAGE_SIZE,
+  DOCUMENTS_MAX_COMMENTS_PER_DOCUMENT,
+} from '../../../lib/historyPolicy'
+import { readNumber, readRecord } from '../documentUi'
+import type { CommentAnchor } from './CommentAnchorNavigation'
+import {
+  bodyContainsPendingMention,
+  findCommentById,
+  readCommentItems,
+  readUserLabels,
+  readWithoutAccess,
+  type DocumentComment,
+  type PendingMention,
+  type UserLabels,
+} from './commentTypes'
+
+type CommentsState =
+  | { status: 'loading' }
+  | { status: 'error'; message: string }
+  | { status: 'ready'; comments: DocumentComment[]; userLabels: UserLabels }
+
+type UseDocumentCommentsInput = {
+  documentId: string
+  editor: Editor | null
+  canComment: boolean
+  canShare: boolean
+}
+
+type GrantAccessDecision = 'share' | 'skip' | 'cancel'
+
+type GrantAccessResolution =
+  | { cancelled: true }
+  | { cancelled: false; grantAccessTo?: string[] }
+
+export function useDocumentComments({ documentId, editor, canComment, canShare }: UseDocumentCommentsInput) {
+  const t = useT()
+  const [state, setState] = React.useState<CommentsState>({ status: 'loading' })
+  const [body, setBody] = React.useState('')
+  const [pendingMentions, setPendingMentions] = React.useState<PendingMention[]>([])
+  const [parentCommentId, setParentCommentId] = React.useState<string | null>(null)
+  const [pendingAnchor, setPendingAnchor] = React.useState<CommentAnchor | null>(null)
+  const [isSubmitting, setIsSubmitting] = React.useState(false)
+  const [resolvingCommentId, setResolvingCommentId] = React.useState<string | null>(null)
+  const [grantAccessNames, setGrantAccessNames] = React.useState<string[] | null>(null)
+  const grantResolver = React.useRef<((decision: GrantAccessDecision) => void) | null>(null)
+  const submissionContextSequence = React.useRef(0)
+  const reloadSequence = React.useRef(0)
+  const activeReload = React.useRef<AbortController | null>(null)
+  const activeDocumentId = React.useRef<string | null>(null)
+  const mutationContextId = `documents-comments:${documentId}`
+  const { runMutation, retryLastMutation } = useGuardedMutation<{
+    formId: string
+    resourceKind: string
+    resourceId: string
+    retryLastMutation: () => Promise<boolean>
+  }>({ contextId: mutationContextId, blockedMessage: t('ui.forms.flash.saveBlocked') })
+  const activePendingMentions = React.useMemo(
+    () => pendingMentions.filter((mention) => bodyContainsPendingMention(body, mention)),
+    [body, pendingMentions],
+  )
+
+  const reload = React.useCallback(async () => {
+    const reloadId = ++reloadSequence.current
+    const controller = new AbortController()
+    activeReload.current?.abort()
+    activeReload.current = controller
+    const isCurrent = () => reloadSequence.current === reloadId && !controller.signal.aborted
+    const documentChanged = activeDocumentId.current !== documentId
+    activeDocumentId.current = documentId
+    setState((current) => !documentChanged && current.status === 'ready' ? current : { status: 'loading' })
+    try {
+      const maxPages = Math.ceil(DOCUMENTS_MAX_COMMENTS_PER_DOCUMENT / DOCUMENTS_COMMENT_LIST_PAGE_SIZE)
+      const pathForPage = (page: number) => (
+        `/api/documents/${encodeURIComponent(documentId)}/comments?page=${page}&pageSize=${DOCUMENTS_COMMENT_LIST_PAGE_SIZE}`
+      )
+      const firstCall = await apiCall<unknown>(pathForPage(1), { signal: controller.signal })
+      if (!isCurrent()) return
+      if (!firstCall.ok) {
+        setState({ status: 'error', message: t('documents.comments.error.load') })
+        return
+      }
+
+      const firstRoot = readRecord(firstCall.result)
+      const totalPages = Math.min(
+        maxPages,
+        Math.max(1, firstRoot ? readNumber(firstRoot, 'totalPages', 'total_pages') ?? 1 : 1),
+      )
+      const remainingCalls = totalPages > 1
+        ? await Promise.all(Array.from({ length: totalPages - 1 }, (_, index) => (
+            apiCall<unknown>(pathForPage(index + 2), { signal: controller.signal })
+          )))
+        : []
+      if (!isCurrent()) return
+      if (remainingCalls.some((call) => !call.ok)) {
+        setState({ status: 'error', message: t('documents.comments.error.load') })
+        return
+      }
+
+      const calls = [firstCall, ...remainingCalls]
+      const comments = [...calls].reverse().flatMap((call) => readCommentItems(call.result))
+      const userLabels = calls.reduce<UserLabels>((labels, call) => ({
+        ...labels,
+        ...readUserLabels(call.result, t('documents.users.unknown')),
+      }), {})
+      setState({ status: 'ready', comments, userLabels })
+    } catch (error) {
+      if (isCurrent()) {
+        setState({ status: 'error', message: error instanceof Error ? error.message : t('documents.comments.error.load') })
+      }
+    } finally {
+      if (activeReload.current === controller) activeReload.current = null
+    }
+  }, [documentId, t])
+
+  React.useEffect(() => {
+    void reload()
+    return () => {
+      reloadSequence.current += 1
+      activeReload.current?.abort()
+      activeReload.current = null
+    }
+  }, [reload])
+
+  const cancelPendingGrantAccess = React.useCallback(() => {
+    const resolve = grantResolver.current
+    grantResolver.current = null
+    resolve?.('cancel')
+  }, [])
+
+  React.useEffect(() => {
+    setGrantAccessNames(null)
+    setIsSubmitting(false)
+    return () => {
+      submissionContextSequence.current += 1
+      cancelPendingGrantAccess()
+    }
+  }, [cancelPendingGrantAccess, documentId])
+
+  const labelFor = React.useCallback((userId: string) => {
+    const labels = state.status === 'ready' ? state.userLabels : {}
+    return labels[userId.toLowerCase()]?.label ?? t('documents.users.unknown')
+  }, [state, t])
+
+  const resetComposer = React.useCallback(() => {
+    setBody('')
+    setPendingMentions([])
+    setParentCommentId(null)
+    setPendingAnchor(null)
+  }, [])
+
+  const chooseGrantAccess = React.useCallback((share: boolean) => {
+    const resolve = grantResolver.current
+    grantResolver.current = null
+    setGrantAccessNames(null)
+    resolve?.(share ? 'share' : 'skip')
+  }, [])
+
+  const requestGrantAccess = React.useCallback((names: string[]) => new Promise<GrantAccessDecision>((resolve) => {
+    cancelPendingGrantAccess()
+    grantResolver.current = resolve
+    setGrantAccessNames(names)
+  }), [cancelPendingGrantAccess])
+
+  const resolveGrantAccessTo = React.useCallback(async (
+    isCurrentSubmission: () => boolean,
+  ): Promise<GrantAccessResolution> => {
+    const userIds = Array.from(new Set(activePendingMentions.map((mention) => mention.userId.toLowerCase())))
+    if (userIds.length === 0) return { cancelled: false }
+    // Intentionally outside useGuardedMutation: access-check is read-shaped
+    // (a POST only to carry the user-id list in the body) and mutates nothing.
+    const call = await apiCall<unknown>(
+      `/api/documents/${encodeURIComponent(documentId)}/comments/access-check`,
+      { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ userIds }) },
+    )
+    if (!isCurrentSubmission()) return { cancelled: true }
+    if (!call.ok) throw new Error(t('documents.comments.error.save'))
+    const withoutAccess = readWithoutAccess(call.result)
+    if (withoutAccess.length === 0) return { cancelled: false }
+    if (!canShare) {
+      flash(t('documents.comments.grant.noAccessInfo'), 'info')
+      return { cancelled: false, grantAccessTo: [] }
+    }
+    const pendingMentionNames = new Map(
+      activePendingMentions.map((mention) => [mention.userId.toLowerCase(), mention.name]),
+    )
+    const decision = await requestGrantAccess(withoutAccess.map((user) => (
+      pendingMentionNames.get(user.userId) ?? user.label ?? labelFor(user.userId)
+    )))
+    if (decision === 'cancel' || !isCurrentSubmission()) return { cancelled: true }
+    return {
+      cancelled: false,
+      grantAccessTo: decision === 'share' ? withoutAccess.map((user) => user.userId) : [],
+    }
+  }, [activePendingMentions, canShare, documentId, labelFor, requestGrantAccess, t])
+
+  const submit = React.useCallback(async () => {
+    const trimmedBody = body.trim()
+    if (!trimmedBody || !canComment) return
+    const submissionSequence = submissionContextSequence.current
+    const isCurrentSubmission = () => submissionContextSequence.current === submissionSequence
+    setIsSubmitting(true)
+    try {
+      const grantResolution = await resolveGrantAccessTo(isCurrentSubmission)
+      if (grantResolution.cancelled || !isCurrentSubmission()) return
+      const anchor = pendingAnchor ?? (editor
+        ? (await import('./CommentAnchorNavigation')).captureCommentAnchor(editor)
+        : null)
+      if (!isCurrentSubmission()) return
+      const mentions = activePendingMentions.map(({ userId }) => ({ userId }))
+      await runMutation({
+        operation: () => apiCallOrThrow(
+          `/api/documents/${encodeURIComponent(documentId)}/comments`,
+          {
+            method: 'POST', headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+              body: trimmedBody,
+              anchor,
+              parentCommentId,
+              mentions,
+              grantAccessTo: grantResolution.grantAccessTo,
+            }),
+          },
+          { errorMessage: t('documents.comments.error.save') },
+        ),
+        context: { formId: mutationContextId, resourceKind: 'documents.document_comment', resourceId: documentId, retryLastMutation },
+        mutationPayload: { body: trimmedBody, parentCommentId, mentions },
+      })
+      if (!isCurrentSubmission()) return
+      resetComposer()
+      await reload()
+    } catch (error) {
+      if (isCurrentSubmission()) {
+        flash(error instanceof Error ? error.message : t('documents.comments.error.save'), 'error')
+      }
+    } finally {
+      if (isCurrentSubmission()) setIsSubmitting(false)
+    }
+  }, [activePendingMentions, body, canComment, documentId, editor, mutationContextId, parentCommentId, pendingAnchor, reload, resetComposer, resolveGrantAccessTo, retryLastMutation, runMutation, t])
+
+  const resolveComment = React.useCallback(async (comment: DocumentComment) => {
+    if (!comment.canResolve) return
+    setResolvingCommentId(comment.id)
+    try {
+      await runMutation({
+        operation: () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(comment.updatedAt),
+          () => apiCallOrThrow(
+            `/api/documents/${encodeURIComponent(documentId)}/comments`,
+            { method: 'PATCH', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ id: comment.id, resolved: comment.resolvedAt === null }) },
+            { errorMessage: t('documents.comments.error.save') },
+          ),
+        ),
+        context: { formId: mutationContextId, resourceKind: 'documents.document_comment', resourceId: comment.id, retryLastMutation },
+        mutationPayload: { id: comment.id, resolved: comment.resolvedAt === null },
+      })
+      await reload()
+    } catch (error) {
+      if (!surfaceRecordConflict(error, t, { onRefresh: () => { void reload() } })) {
+        flash(error instanceof Error ? error.message : t('documents.comments.error.save'), 'error')
+      }
+    } finally {
+      setResolvingCommentId(null)
+    }
+  }, [documentId, mutationContextId, reload, retryLastMutation, runMutation, t])
+
+  const comments = state.status === 'ready' ? state.comments : []
+  const parentComment = parentCommentId ? findCommentById(comments, parentCommentId) : null
+  return {
+    state, comments, body, setBody, pendingMentions, setPendingMentions, parentCommentId,
+    pendingAnchor, setPendingAnchor, isSubmitting, resolvingCommentId, grantAccessNames,
+    chooseGrantAccess, labelFor, resetComposer, reload, submit, resolveComment,
+    startReply: (comment: DocumentComment) => { setPendingAnchor(null); setParentCommentId(comment.id) },
+    replyToName: parentComment ? labelFor(parentComment.authorUserId) : null,
+  }
+}

package/src/modules/documents/backend/documents/[id]/useDocumentEditor.ts

@@ -0,0 +1,157 @@
+"use client"
+
+import * as React from 'react'
+import type { Editor } from '@tiptap/core'
+import type { Node as ProseMirrorNode } from '@tiptap/pm/model'
+import { useEditor } from '@tiptap/react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import {
+  activateEntityRefFromKeyboardEvent,
+  activateEntityRefFromPointerEvent,
+  getClientEditorExtras,
+  getCollaborativeEditorExtensions,
+  getDocumentEditorExtensions,
+} from '../../../lib/editorConfig'
+import { createEntitySuggestionExtension } from '../../../lib/entitySuggestion'
+import { DocumentPagination } from './documentPagination'
+import type { CollabResources, EditorSelectionRange, EditorWordCount } from './editorTypes'
+
+type UseDocumentEditorInput = {
+  documentId: string
+  initialContentHtml: string
+  editorMode: 'collab' | 'fallback'
+  collabResources?: CollabResources
+  readOnly: boolean
+  onEditorReady?: (editor: Editor | null) => void
+  onUpdate?: (editor: Editor) => void
+  onEntitySuggestion: (range: EditorSelectionRange) => void
+  onSuggestionClose: () => void
+}
+
+export const DOCUMENT_COUNT_UPDATE_DELAY_MS = 150
+
+export function countDocumentWordsAndCharacters(doc: ProseMirrorNode): EditorWordCount {
+  let words = 0
+  let characters = 0
+  let firstBlock = true
+  let insideWord = false
+
+  doc.nodesBetween(0, doc.content.size, (node) => {
+    const nodeText = node.isText ? node.text ?? '' : node.isLeaf ? ' ' : ''
+    if (node.isBlock && ((node.isLeaf && nodeText.length > 0) || node.isTextblock)) {
+      if (firstBlock) firstBlock = false
+      else insideWord = false
+    }
+    characters += nodeText.length
+    for (let index = 0; index < nodeText.length; index += 1) {
+      if (nodeText[index] === ' ') {
+        insideWord = false
+      } else if (!insideWord) {
+        words += 1
+        insideWord = true
+      }
+    }
+  })
+  return { words, characters }
+}
+
+function documentCounts(editor: Editor | null): EditorWordCount {
+  if (!editor) return { words: 0, characters: 0 }
+  return countDocumentWordsAndCharacters(editor.state.doc)
+}
+
+export function useDocumentEditor(input: UseDocumentEditorInput) {
+  const t = useT()
+  const editorRef = React.useRef<Editor | null>(null)
+  const countTimerRef = React.useRef<number | null>(null)
+  const readOnlyRef = React.useRef(input.readOnly)
+  const onEntitySuggestionRef = React.useRef(input.onEntitySuggestion)
+  const onSuggestionCloseRef = React.useRef(input.onSuggestionClose)
+  const [counts, setCounts] = React.useState<EditorWordCount>({ words: 0, characters: 0 })
+  readOnlyRef.current = input.readOnly
+  onEntitySuggestionRef.current = input.onEntitySuggestion
+  onSuggestionCloseRef.current = input.onSuggestionClose
+
+  const applyCounts = React.useCallback((updated: Editor | null) => {
+    const next = documentCounts(updated)
+    React.startTransition(() => {
+      setCounts((current) => current.words === next.words && current.characters === next.characters ? current : next)
+    })
+  }, [])
+  const scheduleCounts = React.useCallback((updated: Editor) => {
+    if (countTimerRef.current !== null) window.clearTimeout(countTimerRef.current)
+    countTimerRef.current = window.setTimeout(() => {
+      countTimerRef.current = null
+      applyCounts(updated)
+    }, DOCUMENT_COUNT_UPDATE_DELAY_MS)
+  }, [applyCounts])
+
+  const extensions = React.useMemo(() => {
+    const suggestions = [createEntitySuggestionExtension({
+      onTrigger: ({ range }) => {
+        if (!readOnlyRef.current) onEntitySuggestionRef.current(range)
+      },
+      onClose: () => onSuggestionCloseRef.current(),
+    })]
+    return input.editorMode === 'collab' && input.collabResources
+      ? [...getCollaborativeEditorExtensions({
+        ydoc: input.collabResources.ydoc,
+        provider: input.collabResources.provider,
+        user: input.collabResources.user,
+        placeholder: t('documents.editor.placeholder'),
+        fallbackUserLabel: t('documents.users.unknown'),
+        fallbackEntityRefLabel: t('documents.editor.entityRef.fallbackLabel'),
+      }), ...getClientEditorExtras(), DocumentPagination, ...suggestions]
+      : [...getDocumentEditorExtensions({
+        entityRefFallbackLabel: t('documents.editor.entityRef.fallbackLabel'),
+      }), ...getClientEditorExtras(), DocumentPagination, ...suggestions]
+  }, [input.collabResources, input.editorMode, t])
+
+  const editor = useEditor({
+    extensions,
+    content: input.editorMode === 'fallback' ? input.initialContentHtml : undefined,
+    editable: !input.readOnly,
+    editorProps: {
+      attributes: {
+        class: 'min-h-96 text-base leading-7 text-foreground focus-visible:outline-none',
+        role: 'textbox',
+        'aria-label': t('documents.editor.content.ariaLabel'),
+        'aria-multiline': 'true',
+      },
+      handleClick(_view, _position, event) {
+        return activateEntityRefFromPointerEvent(
+          event,
+          (href) => { window.open(href, '_blank', 'noopener') },
+        )
+      },
+      handleKeyDown(_view, event) {
+        return activateEntityRefFromKeyboardEvent(
+          event,
+          (href) => { window.open(href, '_blank', 'noopener') },
+        )
+      },
+    },
+    onCreate: ({ editor: created }) => { editorRef.current = created; applyCounts(created); input.onEditorReady?.(created) },
+    onDestroy: () => {
+      if (countTimerRef.current !== null) window.clearTimeout(countTimerRef.current)
+      countTimerRef.current = null
+      editorRef.current = null
+      input.onEditorReady?.(null)
+    },
+    onUpdate: ({ editor: updated }) => {
+      editorRef.current = updated
+      scheduleCounts(updated)
+      input.onUpdate?.(updated)
+    },
+  }, [input.documentId, input.editorMode, extensions])
+
+  React.useEffect(() => { editorRef.current = editor; editor?.setEditable(!input.readOnly) }, [editor, input.readOnly])
+  React.useEffect(() => {
+    if (input.readOnly) onSuggestionCloseRef.current()
+  }, [input.readOnly])
+  React.useEffect(() => () => {
+    if (countTimerRef.current !== null) window.clearTimeout(countTimerRef.current)
+  }, [])
+  React.useEffect(() => () => { input.onEditorReady?.(null) }, [input.onEditorReady])
+  return { editor, editorRef, counts }
+}

package/src/modules/documents/backend/documents/[id]/useDocumentTitle.ts

@@ -0,0 +1,77 @@
+"use client"
+
+import * as React from 'react'
+import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+
+function readUpdatedAt(payload: unknown): string | null {
+  if (!payload || typeof payload !== 'object') return null
+  const record = payload as Record<string, unknown>
+  const value = record.updatedAt ?? record.updated_at
+  return typeof value === 'string' ? value : null
+}
+
+export function useDocumentTitle(input: {
+  documentId: string
+  title: string
+  updatedAt: string | null
+  readOnly: boolean
+  onTitleChange?: (title: string, updatedAt: string | null) => void
+}) {
+  const t = useT()
+  const committed = React.useRef(input.title)
+  const version = React.useRef(input.updatedAt)
+  const draft = React.useRef(input.title)
+  const [value, setValueState] = React.useState(input.title)
+  const [saving, setSaving] = React.useState(false)
+  const setValue = React.useCallback((next: string) => {
+    draft.current = next
+    setValueState(next)
+  }, [])
+  const mutationContextId = `documents-title:${input.documentId}`
+  const { runMutation, retryLastMutation } = useGuardedMutation<{
+    formId: string
+    resourceKind: string
+    resourceId: string
+    retryLastMutation: () => Promise<boolean>
+  }>({ contextId: mutationContextId, blockedMessage: t('ui.forms.flash.saveBlocked') })
+  React.useEffect(() => { committed.current = input.title; setValue(input.title) }, [input.title, setValue])
+  React.useEffect(() => { version.current = input.updatedAt }, [input.updatedAt])
+
+  const commit = React.useCallback(async () => {
+    const title = draft.current.trim()
+    if (input.readOnly || saving || !title || title === committed.current) { setValue(committed.current); return }
+    setSaving(true)
+    try {
+      const call = await runMutation({
+        operation: () => withScopedApiRequestHeaders(buildOptimisticLockHeader(version.current), async () => {
+          const result = await apiCall<unknown>(
+            `/api/documents/${encodeURIComponent(input.documentId)}`,
+            { method: 'PUT', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ id: input.documentId, title }) },
+          )
+          if (!result.ok) throw Object.assign(new Error(t('documents.editor.error.rename')), { status: result.status, body: result.result })
+          return result
+        }),
+        context: { formId: mutationContextId, resourceKind: 'documents.document', resourceId: input.documentId, retryLastMutation },
+        mutationPayload: { id: input.documentId, title },
+      })
+      version.current = readUpdatedAt(call.result) ?? version.current
+      committed.current = title
+      setValue(title)
+      input.onTitleChange?.(title, version.current)
+    } catch (error) {
+      if (!surfaceRecordConflict(error, t)) flash(error instanceof Error ? error.message : t('documents.editor.error.rename'), 'error')
+      setValue(committed.current)
+    } finally { setSaving(false) }
+  }, [input.documentId, input.onTitleChange, input.readOnly, mutationContextId, retryLastMutation, runMutation, saving, setValue, t])
+
+  const onKeyDown = React.useCallback((event: React.KeyboardEvent<HTMLInputElement>) => {
+    if (event.key === 'Enter') { event.preventDefault(); event.currentTarget.blur() }
+    if (event.key === 'Escape') { event.preventDefault(); setValue(committed.current); event.currentTarget.blur() }
+  }, [setValue])
+  return { value, setValue, saving, commit, onKeyDown }
+}

package/src/modules/documents/backend/documents/[id]/useEditorInsertions.ts

@@ -0,0 +1,147 @@
+"use client"
+
+import * as React from 'react'
+import type { Editor } from '@tiptap/core'
+import { apiCallOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import type { EntityRefAttributes } from '../../../lib/editorConfig'
+import { insertEntityRef } from '../../../lib/entitySuggestion'
+import type { EntityPickerSelection } from '../components/EntityPicker'
+import type { EditorSelectionRange } from './editorTypes'
+
+function readRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' ? value as Record<string, unknown> : null
+}
+
+function readAttachmentUrl(documentId: string, payload: unknown): string | null {
+  const root = readRecord(payload)
+  if (!root) return null
+  const records = [root, readRecord(root.item), readRecord(root.attachment)].filter((value): value is Record<string, unknown> => value !== null)
+  for (const record of records) {
+    const value = record.documentUrl ?? record.document_url ?? record.proxyUrl ?? record.proxy_url ?? record.url
+    if (typeof value === 'string' && value.includes(`/api/documents/${documentId}/attachments/`)) return value
+  }
+  const id = records.map((record) => record.attachmentId ?? record.attachment_id ?? record.id).find((value) => typeof value === 'string')
+  return typeof id === 'string' ? `/api/documents/${encodeURIComponent(documentId)}/attachments/${encodeURIComponent(id)}` : null
+}
+
+export function useEditorInsertions(input: {
+  documentId: string
+  editorRef: React.RefObject<Editor | null>
+  disabled: boolean
+  suggestionRange: EditorSelectionRange | null
+  setSuggestionRange: (range: EditorSelectionRange | null) => void
+}) {
+  const t = useT()
+  const fileInputRef = React.useRef<HTMLInputElement | null>(null)
+  const [linkOpen, setLinkOpen] = React.useState(false)
+  const [linkHref, setLinkHref] = React.useState('')
+  const [entityPickerOpen, setEntityPickerOpen] = React.useState(false)
+  const [recordFieldsLinkId, setRecordFieldsLinkId] = React.useState<string | null>(null)
+  const [uploading, setUploading] = React.useState(false)
+  const mutationContextId = `documents-insertions:${input.documentId}`
+  const { runMutation, retryLastMutation } = useGuardedMutation<{
+    formId: string
+    resourceKind: string
+    resourceId: string
+    retryLastMutation: () => Promise<boolean>
+  }>({ contextId: mutationContextId, blockedMessage: t('ui.forms.flash.saveBlocked') })
+
+  const openLink = React.useCallback(() => {
+    const editor = input.editorRef.current
+    if (!editor || input.disabled) return
+    const href = editor.getAttributes('link').href
+    setLinkHref(typeof href === 'string' ? href : '')
+    setLinkOpen(true)
+  }, [input.disabled, input.editorRef])
+
+  const applyLink = React.useCallback(() => {
+    const editor = input.editorRef.current
+    if (!editor || input.disabled) return
+    const href = linkHref.trim()
+    if (href) {
+      // TipTap rejects a disallowed URI scheme by returning false instead of
+      // throwing. Closing regardless would drop the user's link without a word.
+      if (!editor.chain().focus().extendMarkRange('link').setLink({ href }).run()) {
+        flash(t('documents.editor.link.rejected'), 'error')
+        return
+      }
+    } else {
+      editor.chain().focus().unsetLink().run()
+    }
+    setLinkOpen(false)
+  }, [input.disabled, input.editorRef, linkHref, t])
+
+  const removeLink = React.useCallback(() => {
+    input.editorRef.current?.chain().focus().unsetLink().run()
+    setLinkOpen(false)
+  }, [input.editorRef])
+
+  const handleFiles = React.useCallback(async (files: FileList | null) => {
+    const file = files?.item(0)
+    const editor = input.editorRef.current
+    if (!file || !editor || input.disabled) return
+    setUploading(true)
+    try {
+      const formData = new FormData()
+      formData.set('file', file)
+      const call = await runMutation({
+        operation: () => apiCallOrThrow(
+          `/api/documents/${encodeURIComponent(input.documentId)}/attachments`,
+          { method: 'POST', body: formData },
+          { errorMessage: t('documents.editor.error.imageUpload') },
+        ),
+        context: { formId: mutationContextId, resourceKind: 'documents.document_attachment', resourceId: input.documentId, retryLastMutation },
+        mutationPayload: { fileName: file.name, fileType: file.type },
+      })
+      const url = readAttachmentUrl(input.documentId, call.result)
+      if (!url) throw new Error(t('documents.editor.error.imageUpload'))
+      editor.chain().focus().setImage({ src: url }).run()
+    } catch (error) { flash(error instanceof Error ? error.message : t('documents.editor.error.imageUpload'), 'error') }
+    finally { setUploading(false); if (fileInputRef.current) fileInputRef.current.value = '' }
+  }, [input.disabled, input.documentId, input.editorRef, mutationContextId, retryLastMutation, runMutation, t])
+
+  const handleEntityPick = React.useCallback(async (pick: EntityPickerSelection) => {
+    const editor = input.editorRef.current
+    if (!editor || input.disabled) return
+    try {
+      const call = await runMutation({
+        operation: () => apiCallOrThrow(
+          `/api/documents/${encodeURIComponent(input.documentId)}/links`,
+          {
+            method: 'POST', headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ entityType: pick.type, entityId: pick.id, label: pick.label, href: pick.href, source: 'chip' }),
+          },
+          { errorMessage: t('documents.relatedRecords.error.link') },
+        ),
+        context: { formId: mutationContextId, resourceKind: 'documents.document_entity_link', resourceId: input.documentId, retryLastMutation },
+        mutationPayload: { entityType: pick.type, entityId: pick.id },
+      })
+      const linkId = readRecord(call.result)?.id
+      if (typeof linkId !== 'string' || linkId.length === 0) {
+        throw new Error(t('documents.relatedRecords.error.link'))
+      }
+      const attrs: EntityRefAttributes = { entityType: pick.type, entityId: pick.id, label: pick.label, href: pick.href }
+      if (input.suggestionRange) editor.chain().focus().deleteRange(input.suggestionRange).run()
+      insertEntityRef(editor, attrs)
+      setEntityPickerOpen(false)
+      setRecordFieldsLinkId(linkId)
+      input.setSuggestionRange(null)
+    } catch (error) { flash(error instanceof Error ? error.message : t('documents.relatedRecords.error.link'), 'error') }
+  }, [input.disabled, input.documentId, input.editorRef, input.setSuggestionRange, input.suggestionRange, mutationContextId, retryLastMutation, runMutation, t])
+
+  const setPickerOpen = React.useCallback((open: boolean) => {
+    setEntityPickerOpen(open)
+    if (!open) input.setSuggestionRange(null)
+  }, [input.setSuggestionRange])
+
+  return {
+    fileInputRef, uploading, handleFiles, linkOpen, setLinkOpen, linkHref, setLinkHref,
+    openLink, applyLink, removeLink, entityPickerOpen, setPickerOpen,
+    openEntityPicker: () => { input.setSuggestionRange(null); setEntityPickerOpen(true) },
+    handleEntityPick, recordFieldsLinkId,
+    closeRecordFields: () => setRecordFieldsLinkId(null),
+  }
+}