@tessera-editor/core 0.1.0

package/src/__tests__/writeback.test.ts

@@ -0,0 +1,123 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from 'vitest'
+import { Editor } from '@tiptap/core'
+import { createTesseraExtensions } from '../preset'
+import {
+  getTopLevelBlocks,
+  getBlockJson,
+  appendBlocks,
+  modifyRange,
+  removeBlocks,
+} from '../writeback'
+
+function makeEditor() {
+  return new Editor({ extensions: createTesseraExtensions({ locale: 'zh-CN' }) })
+}
+
+const twoParas = {
+  type: 'doc',
+  content: [
+    { type: 'paragraph', content: [{ type: 'text', text: 'Alpha' }] },
+    { type: 'paragraph', content: [{ type: 'text', text: 'Beta' }] },
+    { type: 'paragraph', content: [{ type: 'text', text: 'Gamma' }] },
+  ],
+}
+
+describe('write-back protocol', () => {
+  it('assigns stable ids to top-level blocks', () => {
+    const editor = makeEditor()
+    editor.commands.setContent(twoParas)
+    const blocks = getTopLevelBlocks(editor)
+    expect(blocks).toHaveLength(3)
+    expect(blocks.every(b => typeof b.id === 'string' && b.id!.length > 0)).toBe(true)
+    editor.destroy()
+  })
+
+  it('ids survive unrelated edits', () => {
+    const editor = makeEditor()
+    editor.commands.setContent(twoParas)
+    const before = getTopLevelBlocks(editor).map(b => b.id)
+    editor.commands.focus('end')
+    editor.commands.insertContent(' tail')
+    const after = getTopLevelBlocks(editor).map(b => b.id)
+    expect(after).toEqual(before)
+    editor.destroy()
+  })
+
+  it('getBlockJson returns the block subtree', () => {
+    const editor = makeEditor()
+    editor.commands.setContent(twoParas)
+    const first = getTopLevelBlocks(editor)[0]!
+    const json = getBlockJson(editor, first.id as string)
+    expect(json?.type).toBe('paragraph')
+    expect(json?.content?.[0]?.text).toBe('Alpha')
+    editor.destroy()
+  })
+
+  it('appendBlocks appends at end and after a given id', () => {
+    const editor = makeEditor()
+    editor.commands.setContent(twoParas)
+    const blocks = getTopLevelBlocks(editor)
+
+    expect(appendBlocks(editor, { content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Delta' }] }] })).toBe(true)
+    expect(editor.state.doc.childCount).toBe(4)
+
+    const second = blocks[1]!
+    expect(appendBlocks(editor, { afterId: second.id as string, content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Inserted' }] }] })).toBe(true)
+    const texts = getTopLevelBlocks(editor).map(b => b.node.textContent)
+    expect(texts).toEqual(['Alpha', 'Beta', 'Inserted', 'Gamma', 'Delta'])
+    editor.destroy()
+  })
+
+  it('modifyRange replaces an inclusive id range with new content', () => {
+    const editor = makeEditor()
+    editor.commands.setContent(twoParas)
+    const blocks = getTopLevelBlocks(editor)
+
+    expect(
+      modifyRange(editor, {
+        fromId: blocks[0]!.id as string,
+        toId: blocks[1]!.id as string,
+        content: [{ type: 'heading', attrs: { level: 2 }, content: [{ type: 'text', text: 'Replaced' }] }],
+      }),
+    ).toBe(true)
+
+    const after = getTopLevelBlocks(editor)
+    expect(after).toHaveLength(2)
+    expect(after[0]!.type).toBe('heading')
+    expect(after[0]!.node.textContent).toBe('Replaced')
+    expect(after[1]!.node.textContent).toBe('Gamma')
+    editor.destroy()
+  })
+
+  it('removeBlocks deletes blocks by ids in one step', () => {
+    const editor = makeEditor()
+    editor.commands.setContent(twoParas)
+    const ids = getTopLevelBlocks(editor)
+      .slice(0, 2)
+      .map(b => b.id as string)
+    expect(removeBlocks(editor, ids)).toBe(true)
+    const after = getTopLevelBlocks(editor)
+    expect(after).toHaveLength(1)
+    expect(after[0]!.node.textContent).toBe('Gamma')
+    editor.destroy()
+  })
+
+  it('modifyRange as one transaction = one undo step (with realistic spacing)', async () => {
+    const editor = makeEditor()
+    editor.commands.setContent(twoParas)
+    // prosemirror-history merges adjacent edits within newGroupDelay (500ms);
+    // space the operations like real usage so the write-back owns its undo step.
+    await new Promise(resolve => setTimeout(resolve, 550))
+    const blocks = getTopLevelBlocks(editor)
+    modifyRange(editor, {
+      fromId: blocks[0]!.id as string,
+      toId: blocks[2]!.id as string,
+      content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Solo' }] }],
+    })
+    expect(editor.state.doc.childCount).toBe(1)
+    editor.commands.undo()
+    expect(editor.state.doc.childCount).toBe(3)
+    editor.destroy()
+  })
+})

package/src/blockmenu.ts

@@ -0,0 +1,38 @@
+import type { Editor } from '@tiptap/core'
+
+/**
+ * Block menu helpers shared by the right-click context menu and the drag
+ * handle menu (acceptance §5). Pure functions so both bindings — and the
+ * tests — operate on the same logic.
+ */
+
+/** Resolves the document position of a top-level block by its stable id. */
+export function findBlockPosById(editor: Editor, id: string): number | null {
+  let found: number | null = null
+  editor.state.doc.forEach((node, offset) => {
+    if (found === null && node.attrs.id === id) {
+      found = offset
+    }
+  })
+  return found
+}
+
+/** Removes a top-level block by its stable id (single transaction). */
+export function deleteBlockById(editor: Editor, id: string): boolean {
+  const pos = findBlockPosById(editor, id)
+  if (pos === null) {
+    return false
+  }
+  const node = editor.state.doc.nodeAt(pos)
+  if (!node) {
+    return false
+  }
+  const tr = editor.state.tr.delete(pos, pos + node.nodeSize)
+  editor.view.dispatch(tr)
+  return true
+}
+
+/** Anchor URL for a block id (`#block-<id>` on the current page). */
+export function blockAnchorUrl(blockId: string): string {
+  return `${location.origin}${location.pathname}#block-${blockId}`
+}

package/src/diff.ts

@@ -0,0 +1,150 @@
+import type { JSONContent } from '@tiptap/core'
+
+/**
+ * Document diff (v1.1 history panel): block-level via stable ids (LCS on the
+ * id sequence) + word-level inside changed text blocks. Pure utility — the
+ * panel renders it.
+ */
+
+export interface WordDiffPart {
+  text: string
+  type: 'same' | 'add' | 'del'
+}
+
+export interface BlockDiffEntry {
+  kind: 'added' | 'removed' | 'changed' | 'unchanged'
+  id?: string
+  before?: JSONContent
+  after?: JSONContent
+  wordDiff?: WordDiffPart[]
+}
+
+function topLevel(doc: JSONContent): JSONContent[] {
+  return doc.content ?? []
+}
+
+function blockId(block: JSONContent): string | null {
+  const id = block.attrs?.id
+  return typeof id === 'string' ? id : null
+}
+
+function collectText(node: JSONContent): string {
+  let text = ''
+  if (node.text) {
+    text += node.text
+  }
+  for (const child of node.content ?? []) {
+    text += collectText(child)
+  }
+  return text
+}
+
+function tokenize(text: string): string[] {
+  return text.match(/[\u4e00-\u9fa5]|[a-zA-Z0-9]+|\s+|[^\sa-zA-Z0-9\u4e00-\u9fa5]/g) ?? []
+}
+
+/** Classic LCS word diff with a size guard. */
+export function wordDiff(beforeText: string, afterText: string): WordDiffPart[] {
+  const a = tokenize(beforeText)
+  const b = tokenize(afterText)
+  if (a.length * b.length > 4_000_000) {
+    return [
+      { text: beforeText, type: 'del' },
+      { text: afterText, type: 'add' },
+    ]
+  }
+  // dp[i][j] = LCS length of a[i:], b[j:]
+  const dp: Uint32Array[] = Array.from({ length: a.length + 1 }, () => new Uint32Array(b.length + 1))
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) {
+      dp[i]![j] = a[i] === b[j] ? dp[i + 1]![j + 1]! + 1 : Math.max(dp[i + 1]![j]!, dp[i]![j + 1]!)
+    }
+  }
+  const parts: WordDiffPart[] = []
+  const push = (text: string, type: WordDiffPart['type']) => {
+    const last = parts[parts.length - 1]
+    if (last && last.type === type) {
+      last.text += text
+    } else {
+      parts.push({ text, type })
+    }
+  }
+  let i = 0
+  let j = 0
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      push(a[i]!, 'same')
+      i++
+      j++
+    } else if (dp[i + 1]![j]! >= dp[i]![j + 1]!) {
+      push(a[i]!, 'del')
+      i++
+    } else {
+      push(b[j]!, 'add')
+      j++
+    }
+  }
+  while (i < a.length) {
+    push(a[i++]!, 'del')
+  }
+  while (j < b.length) {
+    push(b[j++]!, 'add')
+  }
+  return parts
+}
+
+function sameBlock(a: JSONContent, b: JSONContent): boolean {
+  return JSON.stringify(a) === JSON.stringify(b)
+}
+
+export function diffDocs(before: JSONContent, after: JSONContent): BlockDiffEntry[] {
+  const beforeBlocks = topLevel(before)
+  const afterBlocks = topLevel(after)
+  const afterById = new Map<string, JSONContent>()
+  for (const block of afterBlocks) {
+    const id = blockId(block)
+    if (id) {
+      afterById.set(id, block)
+    }
+  }
+  const seen = new Set<string>()
+  const entries: BlockDiffEntry[] = []
+
+  for (const block of beforeBlocks) {
+    const id = blockId(block)
+    if (id && afterById.has(id)) {
+      seen.add(id)
+      const next = afterById.get(id)!
+      if (sameBlock(block, next)) {
+        entries.push({ kind: 'unchanged', id, before: block, after: next })
+      } else {
+        entries.push({ kind: 'changed', id, before: block, after: next, wordDiff: wordDiff(collectText(block), collectText(next)) })
+      }
+    } else {
+      entries.push({ kind: 'removed', id: id ?? undefined, before: block })
+    }
+  }
+  for (const block of afterBlocks) {
+    const id = blockId(block)
+    if (id && seen.has(id)) {
+      continue
+    }
+    if (!id || !beforeBlocks.some(b => blockId(b) === id)) {
+      entries.push({ kind: 'added', id: id ?? undefined, after: block })
+    }
+  }
+  return entries
+}
+
+/** Compact summary for the panel header. */
+export function diffSummary(entries: BlockDiffEntry[]): { added: number; removed: number; changed: number } {
+  let added = 0
+  let removed = 0
+  let changed = 0
+  for (const entry of entries) {
+    if (entry.kind === 'added') added++
+    else if (entry.kind === 'removed') removed++
+    else if (entry.kind === 'changed') changed++
+  }
+  return { added, removed, changed }
+}

package/src/extensions/context-menu.ts

@@ -0,0 +1,55 @@
+import { Extension } from '@tiptap/core'
+import { Plugin } from '@tiptap/pm/state'
+
+/**
+ * Block context menu (v1.1): right-click a block → `tessera:blockMenu` event.
+ * The binding renders the menu (copy anchor link / copy block id / delete;
+ * row & column ops when the target is a table).
+ */
+export const BlockContextMenu = Extension.create({
+  name: 'tesseraBlockMenu',
+
+  addProseMirrorPlugins() {
+    const editor = this.editor
+    return [
+      new Plugin({
+        props: {
+          handleDOMEvents: {
+            contextmenu: (view, event) => {
+              const coords = view.posAtCoords({ left: event.clientX, top: event.clientY })
+              if (!coords) {
+                return false
+              }
+              const $pos = view.state.doc.resolve(coords.pos)
+              for (let depth = $pos.depth; depth >= 1; depth--) {
+                const node = $pos.node(depth)
+                if (typeof node.attrs.id === 'string') {
+                  editor.emit('tessera:blockMenu', {
+                    blockId: node.attrs.id as string,
+                    blockType: node.type.name,
+                    clientX: event.clientX,
+                    clientY: event.clientY,
+                  })
+                  event.preventDefault()
+                  return true
+                }
+              }
+              return false
+            },
+          },
+        },
+      }),
+    ]
+  },
+})
+
+declare module '@tiptap/core' {
+  interface EditorEvents {
+    'tessera:blockMenu': {
+      blockId: string
+      blockType: string
+      clientX: number
+      clientY: number
+    }
+  }
+}

package/src/extensions/emoji.ts

@@ -0,0 +1,148 @@
+import { Extension } from '@tiptap/core'
+import { PluginKey } from '@tiptap/pm/state'
+import Suggestion from '@tiptap/suggestion'
+import type { SuggestionOptions, SuggestionProps, SuggestionKeyDownProps } from '@tiptap/suggestion'
+
+/**
+ * Emoji picker (acceptance §2, v1.1): typing `:` anywhere opens a picker
+ * filtered by name/keywords; Return / click inserts the emoji and closes.
+ * Runs on @tiptap/suggestion like the slash menu — IME composition guard
+ * comes for free (suggestion ignores composing transactions).
+ */
+
+export interface EmojiItem {
+  char: string
+  name: string
+  keywords: string[]
+}
+
+/** Curated common set; hosts may append via `extraItems`. */
+export const EMOJI_ITEMS: EmojiItem[] = [
+  { char: '😀', name: 'grinning', keywords: ['face', 'happy', 'smile'] },
+  { char: '😄', name: 'smile', keywords: ['face', 'happy', 'joy'] },
+  { char: '😁', name: 'beaming', keywords: ['face', 'grin'] },
+  { char: '😂', name: 'joy', keywords: ['face', 'tears', 'lol'] },
+  { char: '🤣', name: 'rofl', keywords: ['face', 'laugh', 'floor'] },
+  { char: '😊', name: 'blush', keywords: ['face', 'happy', 'warm'] },
+  { char: '🙂', name: 'slight_smile', keywords: ['face', 'smile'] },
+  { char: '😉', name: 'wink', keywords: ['face'] },
+  { char: '😍', name: 'heart_eyes', keywords: ['face', 'love'] },
+  { char: '😘', name: 'kiss', keywords: ['face', 'love'] },
+  { char: '😜', name: 'zany', keywords: ['face', 'crazy', 'tongue'] },
+  { char: '🤔', name: 'thinking', keywords: ['face', 'hmm'] },
+  { char: '🤗', name: 'hug', keywords: ['face'] },
+  { char: '🤨', name: 'eyebrow', keywords: ['face', 'suspicious'] },
+  { char: '😐', name: 'neutral', keywords: ['face', 'meh'] },
+  { char: '😴', name: 'sleeping', keywords: ['face', 'zzz'] },
+  { char: '😪', name: 'sleepy', keywords: ['face', 'tired'] },
+  { char: '😫', name: 'tired', keywords: ['face', 'exhausted'] },
+  { char: '🥳', name: 'partying', keywords: ['face', 'celebrate'] },
+  { char: '😎', name: 'cool', keywords: ['face', 'sunglasses'] },
+  { char: '🤓', name: 'nerd', keywords: ['face', 'glasses'] },
+  { char: '😭', name: 'sob', keywords: ['face', 'cry', 'tears'] },
+  { char: '😡', name: 'angry', keywords: ['face', 'rage'] },
+  { char: '😱', name: 'scream', keywords: ['face', 'fear'] },
+  { char: '🤯', name: 'exploding_head', keywords: ['face', 'mind', 'blown'] },
+  { char: '🥺', name: 'pleading', keywords: ['face', 'puppy'] },
+  { char: '😇', name: 'innocent', keywords: ['face', 'angel', 'halo'] },
+  { char: '🤝', name: 'handshake', keywords: ['hands', 'deal'] },
+  { char: '👍', name: 'thumbsup', keywords: ['hand', 'ok', 'like', 'yes'] },
+  { char: '👎', name: 'thumbsdown', keywords: ['hand', 'dislike', 'no'] },
+  { char: '👌', name: 'ok_hand', keywords: ['hand'] },
+  { char: '✌️', name: 'victory', keywords: ['hand', 'peace'] },
+  { char: '🤞', name: 'crossed_fingers', keywords: ['hand', 'luck'] },
+  { char: '👏', name: 'clap', keywords: ['hands', 'praise'] },
+  { char: '🙏', name: 'pray', keywords: ['hands', 'thanks'] },
+  { char: '💪', name: 'muscle', keywords: ['arm', 'strong'] },
+  { char: '❤️', name: 'heart', keywords: ['love', 'red'] },
+  { char: '🧡', name: 'orange_heart', keywords: ['love'] },
+  { char: '💛', name: 'yellow_heart', keywords: ['love'] },
+  { char: '💚', name: 'green_heart', keywords: ['love'] },
+  { char: '💙', name: 'blue_heart', keywords: ['love'] },
+  { char: '💜', name: 'purple_heart', keywords: ['love'] },
+  { char: '🖤', name: 'black_heart', keywords: ['love'] },
+  { char: '💔', name: 'broken_heart', keywords: ['love', 'sad'] },
+  { char: '⭐', name: 'star', keywords: ['favorite'] },
+  { char: '🌟', name: 'glowing_star', keywords: ['star', 'shine'] },
+  { char: '✨', name: 'sparkles', keywords: ['magic', 'shine', 'ai'] },
+  { char: '🔥', name: 'fire', keywords: ['hot', 'flame'] },
+  { char: '⚡', name: 'zap', keywords: ['lightning', 'fast'] },
+  { char: '💡', name: 'bulb', keywords: ['idea', 'light'] },
+  { char: '✅', name: 'check', keywords: ['done', 'ok', 'complete'] },
+  { char: '❌', name: 'x', keywords: ['wrong', 'no', 'cancel'] },
+  { char: '⚠️', name: 'warning', keywords: ['caution', 'alert'] },
+  { char: '❓', name: 'question', keywords: ['ask', 'help'] },
+  { char: '❗', name: 'exclamation', keywords: ['important'] },
+  { char: '🚀', name: 'rocket', keywords: ['ship', 'launch', 'fast'] },
+  { char: '🎉', name: 'tada', keywords: ['party', 'celebrate', 'congrats'] },
+  { char: '🎊', name: 'confetti', keywords: ['party'] },
+  { char: '🎯', name: 'dart', keywords: ['target', 'goal'] },
+  { char: '📌', name: 'pushpin', keywords: ['pin'] },
+  { char: '📎', name: 'paperclip', keywords: ['attach'] },
+  { char: '📝', name: 'memo', keywords: ['note', 'doc', 'write'] },
+  { char: '📅', name: 'calendar', keywords: ['date', 'schedule'] },
+  { char: '⏰', name: 'alarm', keywords: ['clock', 'time'] },
+  { char: '💰', name: 'moneybag', keywords: ['money', 'cash'] },
+  { char: '🎁', name: 'gift', keywords: ['present'] },
+  { char: '☕', name: 'coffee', keywords: ['drink', 'tea'] },
+  { char: '🍕', name: 'pizza', keywords: ['food'] },
+  { char: '🌈', name: 'rainbow', keywords: ['color'] },
+  { char: '☀️', name: 'sunny', keywords: ['weather', 'sun'] },
+  { char: '🌙', name: 'crescent', keywords: ['weather', 'moon', 'night'] },
+  { char: '☁️', name: 'cloud', keywords: ['weather'] },
+  { char: '👀', name: 'eyes', keywords: ['look', 'watch'] },
+  { char: '🤖', name: 'robot', keywords: ['ai', 'bot'] },
+  { char: '🐞', name: 'bug', keywords: ['insect', 'error'] },
+]
+
+export function filterEmojiItems(query: string, items: EmojiItem[] = EMOJI_ITEMS): EmojiItem[] {
+  const q = query.toLowerCase()
+  if (!q) {
+    return items
+  }
+  return items.filter(
+    item => item.name.toLowerCase().includes(q) || item.keywords.some(k => k.toLowerCase().includes(q)),
+  )
+}
+
+export interface EmojiMenuOptions {
+  /** UI renderer provided by a binding (same contract as the slash menu). */
+  render?: () => {
+    onStart: (props: SuggestionProps<EmojiItem>) => void
+    onUpdate: (props: SuggestionProps<EmojiItem>) => void
+    onExit: (props: SuggestionProps<EmojiItem>) => void
+    onKeyDown?: (props: SuggestionKeyDownProps) => boolean
+  }
+  /** Hosts may append their own emoji entries. */
+  extraItems?: () => EmojiItem[]
+}
+
+export const EmojiMenu = Extension.create<EmojiMenuOptions>({
+  name: 'tesseraEmojiMenu',
+
+  addOptions() {
+    return {
+      render: undefined,
+      extraItems: undefined,
+    }
+  },
+
+  addProseMirrorPlugins() {
+    const options = this.options
+    const items = [...EMOJI_ITEMS, ...(options.extraItems?.() ?? [])]
+
+    return [
+      Suggestion({
+        editor: this.editor,
+        pluginKey: new PluginKey('tesseraEmojiMenu'),
+        char: ':',
+        startOfLine: false,
+        items: ({ query }) => filterEmojiItems(query, items),
+        command: ({ editor: e, range, props }) => {
+          e.chain().focus().insertContentAt(range, `${(props as EmojiItem).char} `).run()
+        },
+        render: options.render as SuggestionOptions<EmojiItem>['render'],
+      }),
+    ]
+  },
+})