@ap666/office-word 0.1.3 → 0.1.6

package/dist/types.d.ts

@@ -2,7 +2,39 @@ import { JSONContent } from '@tiptap/core';
 export type RichTextEditorProps = {
     modelValue?: JSONContent | null;
     editable?: boolean;
+    mode?: 'edit' | 'preview';
+    outlinePlacement?: 'left' | 'right';
+    enabledExportItems?: RichTextEditorExportItemKey[] | null;
+    enabledInsertMenuItems?: RichTextEditorInsertMenuItemKey[] | null;
+    enabledToolbarActions?: RichTextEditorToolbarActionKey[] | null;
     placeholder?: string;
+    collaboration?: RichTextEditorCollaborationOptions | null;
+};
+export type RichTextEditorExportItemKey = 'pdf' | 'html' | 'image' | 'print';
+export type RichTextEditorInsertMenuItemKey = 'image' | 'video' | 'table' | 'local-file' | 'columns' | 'highlight-block' | 'date' | 'code-block' | 'formula' | 'blockquote' | 'emoji' | 'link' | 'divider' | 'countdown' | 'markdown-import';
+export type RichTextEditorToolbarActionKey = 'blockquote';
+export type RichTextEditorCollaborationDocument = {
+    getXmlFragment: (field: string) => unknown;
+};
+export type RichTextEditorCollaborationAwareness = {
+    states: Map<number, unknown>;
+    on: (event: 'update', callback: (...args: unknown[]) => void) => void;
+    setLocalStateField: (field: string, value: unknown) => void;
+};
+export type RichTextEditorCollaborationProvider = {
+    doc?: unknown;
+    awareness: RichTextEditorCollaborationAwareness;
+};
+export type RichTextEditorCollaborationUser = {
+    name: string;
+    color: string;
+    [key: string]: unknown;
+};
+export type RichTextEditorCollaborationOptions = {
+    document: RichTextEditorCollaborationDocument;
+    field?: string;
+    provider?: RichTextEditorCollaborationProvider | null;
+    user?: RichTextEditorCollaborationUser | null;
 };
 export type RichTextEditorAlign = 'left' | 'center' | 'right';
 export type RichTextEditorImagePayload = {
@@ -30,6 +62,12 @@ export type RichTextEditorFilePayload = {
     widthPercent?: number;
     height?: number;
 };
+export type RichTextEditorLocalFilePayload = {
+    url: string;
+    name: string;
+    size?: number;
+    mimeType?: string;
+};
 export type RichTextEditorImageExportOptions = {
     type?: 'image/png' | 'image/jpeg';
     quality?: number;
@@ -41,6 +79,8 @@ export type RichTextEditorInstance = {
     insertImage: (payload: RichTextEditorImagePayload | RichTextEditorImagePayload[]) => boolean;
     insertVideo: (payload: RichTextEditorVideoPayload) => boolean;
     insertFile: (payload: RichTextEditorFilePayload) => boolean;
+    insertLocalFile: (payload: RichTextEditorLocalFilePayload) => boolean;
+    openLocalFilePicker: () => void;
     focus: () => void;
     getJSON: () => JSONContent | null;
 };

package/docs/usage.md

@@ -13,7 +13,56 @@ import { RichTextEditor } from '@ap666/office-word'
 ## Main Capabilities
 
 - rich text editing with a built-in toolbar UI
+- optional Yjs collaboration mode with the same component API
 - export to PDF, image, and HTML through instance methods
 - external upload integration for image, video, and file insertion
 - typed public instance API for Vue `ref` usage
 
+## Collaboration
+
+Use the optional `collaboration` prop to bind the editor to a Yjs document.
+
+```ts
+import * as Y from 'yjs'
+import { WebsocketProvider } from 'y-websocket'
+
+const ydoc = new Y.Doc()
+const provider = new WebsocketProvider('ws://localhost:1234', 'office-word-demo', ydoc)
+```
+
+```vue
+<RichTextEditor
+  v-model="content"
+  :collaboration="{
+    document: ydoc,
+    field: 'content',
+    provider,
+    user: {
+      name: '张三',
+      color: '#3b82f6',
+    },
+  }"
+/>
+```
+
+When `collaboration` is omitted, the editor stays in normal single-user mode. When `provider + user` are passed, the editor also renders remote cursors and remote selections.
+
+## Bundled Yjs Server
+
+The npm package also ships a minimal websocket server example in `yjs/`.
+
+```bash
+cd node_modules/@ap666/office-word/yjs
+npm install
+npm run start
+```
+
+Client side:
+
+```ts
+import * as Y from 'yjs'
+import { WebsocketProvider } from 'y-websocket'
+
+const ydoc = new Y.Doc()
+const provider = new WebsocketProvider('ws://127.0.0.1:1234', 'office-word-demo', ydoc)
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ap666/office-word",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "description": "A reusable Vue 3 rich text editor component built with Tiptap 3.",
   "type": "module",
   "main": "./dist/index.umd.cjs",
@@ -18,6 +18,7 @@
     "dist",
     "README.md",
     "docs",
+    "yjs",
     "LICENSE"
   ],
   "sideEffects": [
@@ -39,6 +40,8 @@
     "@tiptap/core": "^3.22.1",
     "@tiptap/extension-code-block": "^3.22.1",
     "@tiptap/extension-code-block-lowlight": "^3.22.1",
+    "@tiptap/extension-collaboration": "^3.22.2",
+    "@tiptap/extension-collaboration-caret": "^3.22.2",
     "@tiptap/extension-font-family": "^3.22.1",
     "@tiptap/extension-placeholder": "^3.22.1",
     "@tiptap/extension-subscript": "^3.22.1",
@@ -54,8 +57,11 @@
     "@tiptap/pm": "^3.22.1",
     "@tiptap/starter-kit": "^3.22.1",
     "@tiptap/vue-3": "^3.22.1",
+    "@tiptap/y-tiptap": "^3.0.2",
     "lowlight": "^3.3.0",
-    "vue": "^3.5.0"
+    "vue": "^3.5.0",
+    "y-prosemirror": "^1.2.6",
+    "yjs": "^13.6.30"
   },
   "dependencies": {
     "html2canvas": "^1.4.1",

package/yjs/README.md

@@ -0,0 +1,63 @@
+# Yjs Server Example
+
+This folder is shipped with the npm package so consumers can run a minimal `y-websocket`-compatible Yjs server without adding another backend dependency.
+
+## Files
+
+- `index.js`: minimal websocket server compatible with `y-websocket`
+- `package.json`: runtime dependencies and `npm run start`
+
+## Start
+
+```bash
+cd yjs
+npm install
+npm run start
+```
+
+By default the server listens on `ws://0.0.0.0:1234`.
+
+To override host or port:
+
+```bash
+HOST=0.0.0.0 PORT=1234 npm run start
+```
+
+PowerShell:
+
+```powershell
+$env:HOST="0.0.0.0"
+$env:PORT="1234"
+npm run start
+```
+
+## Client Link Example
+
+```ts
+import * as Y from 'yjs'
+import { WebsocketProvider } from 'y-websocket'
+
+const ydoc = new Y.Doc()
+const provider = new WebsocketProvider('ws://127.0.0.1:1234', 'office-word-demo', ydoc)
+```
+
+```vue
+<RichTextEditor
+  v-model="content"
+  :collaboration="{
+    document: ydoc,
+    field: 'content',
+    provider,
+    user: {
+      name: '张三',
+      color: '#3b82f6',
+    },
+  }"
+/>
+```
+
+## Notes
+
+- all collaborators must use the same websocket address and the same room name
+- if clients are on different machines, do not use `127.0.0.1`; use the server's real LAN or public address
+- this sample server is in-memory only; document state is lost after restart

package/yjs/index.js

@@ -0,0 +1,224 @@
+import http from 'node:http'
+
+import * as decoding from 'lib0/decoding'
+import * as encoding from 'lib0/encoding'
+import * as awarenessProtocol from 'y-protocols/awareness'
+import * as syncProtocol from 'y-protocols/sync'
+import WebSocket, { WebSocketServer } from 'ws'
+import * as Y from 'yjs'
+
+const host = process.env.HOST || '0.0.0.0'
+const port = Number(process.env.PORT || 1234)
+
+const messageSync = 0
+const messageAwareness = 1
+const pingTimeout = 30000
+
+const docs = new Map()
+
+function getDoc(name) {
+  const existing = docs.get(name)
+  if (existing) {
+    return existing
+  }
+
+  const doc = new Y.Doc()
+  const awareness = new awarenessProtocol.Awareness(doc)
+  const conns = new Map()
+
+  awareness.setLocalState(null)
+
+  doc.on('update', (update) => {
+    const encoder = encoding.createEncoder()
+    encoding.writeVarUint(encoder, messageSync)
+    syncProtocol.writeUpdate(encoder, update)
+    const message = encoding.toUint8Array(encoder)
+
+    conns.forEach((_, conn) => {
+      send(conn, message)
+    })
+  })
+
+  awareness.on('update', ({ added, updated, removed }, conn) => {
+    const changedClients = added.concat(updated, removed)
+
+    if (conn) {
+      const controlledIds = conns.get(conn)
+      if (controlledIds) {
+        added.forEach((id) => controlledIds.add(id))
+        removed.forEach((id) => controlledIds.delete(id))
+      }
+    }
+
+    const encoder = encoding.createEncoder()
+    encoding.writeVarUint(encoder, messageAwareness)
+    encoding.writeVarUint8Array(
+      encoder,
+      awarenessProtocol.encodeAwarenessUpdate(awareness, changedClients),
+    )
+
+    const message = encoding.toUint8Array(encoder)
+    conns.forEach((_, ws) => {
+      send(ws, message)
+    })
+  })
+
+  const entry = { name, doc, awareness, conns }
+  docs.set(name, entry)
+  return entry
+}
+
+function removeDocIfEmpty(entry) {
+  if (entry.conns.size === 0) {
+    entry.doc.destroy()
+    docs.delete(entry.name)
+  }
+}
+
+function closeConn(entry, conn) {
+  const controlledIds = entry.conns.get(conn)
+
+  if (controlledIds) {
+    entry.conns.delete(conn)
+    awarenessProtocol.removeAwarenessStates(
+      entry.awareness,
+      Array.from(controlledIds),
+      null,
+    )
+  }
+
+  try {
+    conn.close()
+  } catch {
+    // ignore close failures
+  }
+
+  removeDocIfEmpty(entry)
+  console.log(`[disconnect] room=${entry.name} clients=${entry.conns.size}`)
+}
+
+function send(conn, message) {
+  if (conn.readyState !== WebSocket.OPEN && conn.readyState !== WebSocket.CONNECTING) {
+    try {
+      conn.close()
+    } catch {
+      // ignore close failures
+    }
+    return
+  }
+
+  conn.send(message, (error) => {
+    if (error) {
+      try {
+        conn.close()
+      } catch {
+        // ignore close failures
+      }
+    }
+  })
+}
+
+function setupWSConnection(conn, req) {
+  const docName = (req.url || '/').slice(1).split('?')[0] || 'default'
+  const entry = getDoc(docName)
+
+  entry.conns.set(conn, new Set())
+  conn.binaryType = 'arraybuffer'
+
+  conn.on('message', (message) => {
+    try {
+      const decoder = decoding.createDecoder(new Uint8Array(message))
+      const encoder = encoding.createEncoder()
+      const messageType = decoding.readVarUint(decoder)
+
+      switch (messageType) {
+        case messageSync:
+          encoding.writeVarUint(encoder, messageSync)
+          syncProtocol.readSyncMessage(decoder, encoder, entry.doc, conn)
+          if (encoding.length(encoder) > 1) {
+            send(conn, encoding.toUint8Array(encoder))
+          }
+          break
+        case messageAwareness:
+          awarenessProtocol.applyAwarenessUpdate(
+            entry.awareness,
+            decoding.readVarUint8Array(decoder),
+            conn,
+          )
+          break
+        default:
+          break
+      }
+    } catch (error) {
+      console.error('[message-error]', error)
+    }
+  })
+
+  let pongReceived = true
+  const pingInterval = setInterval(() => {
+    if (!pongReceived) {
+      clearInterval(pingInterval)
+      closeConn(entry, conn)
+      return
+    }
+
+    pongReceived = false
+    try {
+      conn.ping()
+    } catch {
+      clearInterval(pingInterval)
+      closeConn(entry, conn)
+    }
+  }, pingTimeout)
+
+  conn.on('pong', () => {
+    pongReceived = true
+  })
+
+  conn.on('close', () => {
+    clearInterval(pingInterval)
+    closeConn(entry, conn)
+  })
+
+  conn.on('error', (error) => {
+    console.error('[socket-error]', error)
+  })
+
+  const syncEncoder = encoding.createEncoder()
+  encoding.writeVarUint(syncEncoder, messageSync)
+  syncProtocol.writeSyncStep1(syncEncoder, entry.doc)
+  send(conn, encoding.toUint8Array(syncEncoder))
+
+  const awarenessStates = entry.awareness.getStates()
+  if (awarenessStates.size > 0) {
+    const awarenessEncoder = encoding.createEncoder()
+    encoding.writeVarUint(awarenessEncoder, messageAwareness)
+    encoding.writeVarUint8Array(
+      awarenessEncoder,
+      awarenessProtocol.encodeAwarenessUpdate(
+        entry.awareness,
+        Array.from(awarenessStates.keys()),
+      ),
+    )
+    send(conn, encoding.toUint8Array(awarenessEncoder))
+  }
+
+  console.log(`[connect] room=${docName} clients=${entry.conns.size}`)
+}
+
+const server = http.createServer((_req, res) => {
+  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' })
+  res.end('ok')
+})
+
+const wss = new WebSocketServer({ noServer: true })
+
+server.on('upgrade', (request, socket, head) => {
+  wss.handleUpgrade(request, socket, head, (ws) => {
+    setupWSConnection(ws, request)
+  })
+})
+
+server.listen(port, host, () => {
+  console.log(`yjs websocket server running at ws://${host}:${port}`)
+})

package/yjs/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@ap666/office-word-yjs-server",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "lib0": "^0.2.102",
+    "ws": "^8.18.0",
+    "y-protocols": "^1.0.6",
+    "yjs": "^13.6.30"
+  }
+}