wendang-react 0.0.0-stage → 0.5.5

package/README.md

@@ -1,3 +1,470 @@
-# Temporary Holding Version
+# Wendang React
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+在 React 应用中编辑和展示文档、工作表与思维导图，支持表格、图片、代码、公式、附件、评论和文档协同。
+
+[在线演示](https://doc.yjmf.com) · [Vue 版本](https://www.npmjs.com/package/wendang-vue) · [数据工具与服务端校验](https://www.npmjs.com/package/wendang) · [源码](https://gitee.com/ztes/wendang)
+
+## 安装
+
+在 React **18.3+ 或 19** 应用中安装：
+
+```sh
+npm install wendang wendang-react yjs y-protocols
+```
+
+项目需已有 `react` 和 `react-dom`。使用 TypeScript 时安装对应的 `@types/react` 和 `@types/react-dom`。
+构建环境使用 Node.js **20.19+**，页面在现代浏览器中运行。应用入口引入一次 `wendang-react/styles.css`。
+
+## 先运行：编辑、预览和本地保存
+
+把下面内容放入 `App.tsx`。不需要后端或额外 UI 组件库：可以输入文字、切换预览、保存到本机，刷新后恢复。
+附件上传、页面搜索和讨论需要接入下文的宿主服务。
+
+```tsx
+import { useEffect, useRef, useState } from 'react'
+import { ContentProvider } from 'wendang-react'
+import { DocumentEditor, type DocumentEditorHandle } from 'wendang-react/document'
+import { DocumentViewer } from 'wendang-react/document/viewer'
+import { ContentSchemaService, SCHEMA_VERSION, requiredSchemaVersion } from 'wendang/schema'
+import type { ProseMirrorDoc } from 'wendang/types'
+import 'wendang-react/styles.css'
+
+const storageKey = 'wendang:demo:document'
+const initialDoc: ProseMirrorDoc = {
+  type: 'doc', content: [{ type: 'paragraph', content: [{ type: 'text', text: '开始写作，在空行输入 / 插入内容。' }] }],
+}
+
+export default function App() {
+  const editor = useRef<DocumentEditorHandle>(null)
+  const [doc, setDoc] = useState(initialDoc)
+  const [schemaVersion, setSchemaVersion] = useState(SCHEMA_VERSION)
+  const [loaded, setLoaded] = useState(false)
+  const [ready, setReady] = useState(false)
+  const [editing, setEditing] = useState(true)
+  const [status, setStatus] = useState('尚未保存')
+  const [error, setError] = useState('')
+
+  useEffect(() => {
+    try {
+      const raw = localStorage.getItem(storageKey)
+      if (raw) {
+        const stored: { doc: ProseMirrorDoc; schemaVersion: number } = JSON.parse(raw)
+        new ContentSchemaService().validate(stored.doc, stored.schemaVersion)
+        setDoc(stored.doc)
+        setSchemaVersion(requiredSchemaVersion(stored.doc, stored.schemaVersion))
+        setStatus('已载入本机内容')
+      }
+      setLoaded(true)
+    } catch (failure) {
+      setError(`读取失败，原始数据仍保留：${String(failure)}`)
+    }
+  }, [])
+
+  async function save() {
+    if (!editor.current?.isReady()) return
+    try {
+      const snapshot = await editor.current.prepareSnapshot()
+      localStorage.setItem(storageKey, JSON.stringify(snapshot))
+      setSchemaVersion(snapshot.schemaVersion)
+      setError('')
+      setStatus('已保存到本机')
+    } catch (failure) { setError(String(failure)) }
+  }
+
+  return <main data-block-select-band style={{ maxWidth: 960, margin: '32px auto', padding: '0 56px' }}>
+    <div style={{ display: 'flex', gap: 12, marginBottom: 24 }}>
+      <button disabled={!loaded} onClick={() => { setReady(false); setEditing(!editing) }}>{editing ? '预览' : '继续编辑'}</button>
+      <button disabled={!ready || !editing} onClick={() => void save()}>保存到本机</button>
+      <span role="status">{status}</span>
+    </div>
+    {error && <p role="alert">{error}</p>}
+    {loaded && <ContentProvider theme="light">
+      {editing ? <DocumentEditor ref={editor} value={doc} schemaVersion={schemaVersion}
+        onChange={value => { setDoc(value); setStatus('有未保存的修改') }}
+        onReady={() => setReady(true)} onError={failure => setError(failure.message)}
+        onNotice={setError} /> : <DocumentViewer value={doc} />}
+    </ContentProvider>}
+  </main>
+}
+```
+
+**布局要点：** 正文左侧需由应用留出约 **56px** 空间，用于空行「＋」、块菜单和表格入口。
+`data-block-select-band` 声明可从留白开始框选的范围。不要在编辑器内部额外缩进正文。
+工作表和独立导图还需要明确的容器高度，示例见下文。
+
+### 编辑操作
+
+| 想做什么 | 操作 |
+| --- | --- |
+| 插入标题、表格、图片、代码等 | 空行输入 `/`，或悬停空行后点左侧蓝色「＋」；表格先选行列数 |
+| 修改文字格式 | 选中文字，在浮动工具栏中选择格式、链接或颜色 |
+| 转换、移动一个块 | 悬停块左侧，点类型图标或抓手打开菜单；按住抓手拖动 |
+| 移动多个块 | 从正文两侧留白拖动框选，再拖动选中区域；Esc 取消，撤销恢复 |
+| 调整表格 | 点表格左上入口、行列选择条或单元格工具栏；支持拖选、合并、底色、对齐和列宽 |
+| 操作图片 | 先点选图片，再用工具条对齐、编辑图注、预览或删除；图片行可重排和调整相对宽度 |
+| 查看大图 | 阅读态点图片；编辑态点选后再次点击，或点「查看大图」；支持缩放、旋转、拖动与同行翻页 |
+| 编辑公式 | 点击公式，在输入框中修改；Enter 确认，Esc 取消 |
+| 设置代码显示 | 工具栏选择语言、折叠、行号、配色与高度；显示设置不改变正文 |
+
+## 对接服务端：加载与保存
+
+建议保存格式为 `{ doc, schemaVersion }`。`DocumentEditor.prepareSnapshot()` 返回的就是这个结构。
+调用时可能因上传、公式编辑、组合输入或未完成的插入操作而拒绝；提示用户完成操作后重试。
+
+```ts
+import type { DocumentEditorHandle } from 'wendang-react/document'
+import type { ProseMirrorDoc } from 'wendang/types'
+import { ContentSchemaService } from 'wendang/schema'
+
+export interface StoredDocument { doc: ProseMirrorDoc; schemaVersion: number }
+
+export async function loadDocument(id: string): Promise<StoredDocument> {
+  const response = await fetch(`/api/documents/${encodeURIComponent(id)}`, { credentials: 'include' })
+  if (!response.ok) throw new Error(`读取失败：${response.status}`)
+  const stored: StoredDocument = await response.json()
+  new ContentSchemaService().validate(stored.doc, stored.schemaVersion)
+  return stored
+}
+
+export async function saveDocument(id: string, editor: Pick<DocumentEditorHandle, 'prepareSnapshot'>) {
+  const snapshot = await editor.prepareSnapshot()
+  const response = await fetch(`/api/documents/${encodeURIComponent(id)}`, {
+    method: 'PUT', credentials: 'include',
+    headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(snapshot),
+  })
+  if (!response.ok) throw new Error(`保存失败：${response.status}`)
+  return snapshot
+}
+```
+
+`/api/*` 是应用实现的接口，下文示例同样如此。服务端应再次校验正文和资源权限后入库。
+把加载结果分别传给 `value` 和 `schemaVersion`；切换文档时用 `<DocumentEditor key={documentId} ... />` 重建实例。
+
+`onChange` 更新本地状态，不能代表服务端已经保存。收到保存成功响应后再显示「已保存」；
+失败保留当前内容。自动保存需串行提交或使用服务端版本校验，避免旧请求覆盖新内容。
+不需要受控状态时，可改用 `defaultValue`；同一个实例不要同时使用两种初始化方式。
+
+### 文档 API
+
+| Props / 回调 | 用途 |
+| --- | --- |
+| `value`、`onChange(doc, meta?)` | 受控内容；`meta.remote` 标识远端同步 |
+| `defaultValue` | 不受控实例的初始内容 |
+| `schemaVersion` | 加载内容的数据版本 |
+| `disabled`、`placeholder` | 编辑开关和空内容提示 |
+| `allowExport`、`canComment` | 导出操作、评论入口开关，默认关闭 |
+| `pageId`、`spaceId` | 资源标识和引用搜索上下文 |
+| `uploadImage`、`uploadFile` | 上传回调；也可通过 Provider 的 `host` 提供 |
+| `inlineComments`、`activeCommentId` | 评论列表及当前高亮讨论 |
+| `onReady`、`onError`、`onNotice`、`onBlur` | 就绪、错误、提示和失焦 |
+| `onRequestComment`、`onInlineMarkClick`、`onCommentsChanged` | 创建行内评论、点评论标记、导图讨论变化 |
+| `onSharePage`、`onConvertToSubpage`、`onSaveAsTemplate` | 应用菜单动作；后两者接收块 JSON，由应用处理 |
+| `collabDoc`、`collabAwareness` | 文档协同，见下文 |
+
+实例方法：
+
+| 方法 | 返回 / 用途 |
+| --- | --- |
+| `isReady()` / `whenReady()` | 查询就绪 / 等待初始化；销毁也会结束等待，之后先检查 `isReady()` |
+| `prepareSnapshot()` | `Promise<{ doc, schemaVersion }>`，保存时优先使用 |
+| `getJSON()` / `getSnapshot()` | 立即读取正文，不等待未完成操作 |
+| `setContent(doc)` | 明确替换内容，协同模式不使用 |
+| `hasPendingTasks()` | 是否存在未完成的上传、输入或插入 |
+| `focus()` / `undo()` / `redo()` | 聚焦、撤销、重做 |
+| `hasSelection()` / `setSelection(from, to?)` | 查询 / 恢复 ProseMirror 文本选区 |
+| `getSelectionForAnchor()` | 评论锚点 `{ quote, prefix, suffix, start }`，无文字返回 `null` |
+| `getSelectionRect()` | 选区首行的视口矩形，无选区返回 `null` |
+
+只读页面用 `DocumentViewer`，主要 Props 为 `value`、`inlineComments`、`activeCommentId`、
+`onMarkClick`、`attachmentFetcher`、`resolvePageLink`、`pageId`、`canComment`、`allowExport`。
+`sameDocument(a,b)` 可从 `wendang-react/document` 导入，用于比较归一化后的正文。
+
+## 宿主服务：附件、页面引用和评论
+
+先建立一个稳定的 `host` 对象，传给 `<ContentProvider host={host}>`。下面可以保存为 `content-host.ts`；
+示例使用 Cookie 登录，改用 Bearer token 时在请求函数中添加应用的认证头。
+
+```ts
+import type { ContentHost } from 'wendang-react'
+import type { CommentItem } from 'wendang/types'
+
+async function json<T>(url: string, init: RequestInit = {}): Promise<T> {
+  const response = await fetch(url, { credentials: 'include', ...init })
+  if (!response.ok) throw new Error(`请求失败：${response.status}`)
+  return await response.json()
+}
+async function write(url: string, method: string, data?: unknown): Promise<void> {
+  const response = await fetch(url, {
+    method, credentials: 'include', headers: { 'Content-Type': 'application/json' },
+    ...(data === undefined ? {} : { body: JSON.stringify(data) }),
+  })
+  if (!response.ok) throw new Error(`操作失败：${response.status}`)
+}
+
+export function createContentHost(scope: string): ContentHost {
+  return {
+    scope,
+    attachments: {
+      async fetch(id) {
+        const response = await fetch(`/api/attachments/${encodeURIComponent(id)}/content`, { credentials: 'include' })
+        if (!response.ok) throw new Error('附件读取失败')
+        return await response.blob()
+      },
+      async uploadImage(file) {
+        const form = new FormData(); form.append('file', file)
+        return await json<{ id: string; alt: string }>('/api/attachments/images', { method: 'POST', body: form })
+      },
+      async uploadFile(file) {
+        const form = new FormData(); form.append('file', file)
+        return await json<{ id: string; filename: string; mimeType: string; size: number }>('/api/attachments/files', { method: 'POST', body: form })
+      },
+    },
+    references: {
+      async search(query, context) {
+        const params = new URLSearchParams({ q: query })
+        if (context.spaceId) params.set('spaceId', context.spaceId)
+        if (context.excludeId) params.set('excludeId', context.excludeId)
+        return await json<Array<{ id: string; title: string }>>(`/api/pages/search?${params}`)
+      },
+      resolve: id => ({ href: `/pages/${encodeURIComponent(id)}` }),
+      navigate: href => { window.location.assign(href) },
+    },
+    comments: {
+      list: id => json<{ items: CommentItem[] }>(`/api/documents/${encodeURIComponent(id)}/comments`),
+      create: (id, body, parentId, target) => write(`/api/documents/${encodeURIComponent(id)}/comments`, 'POST', { body, parentId, target }),
+      update: (id, body) => write(`/api/comments/${encodeURIComponent(id)}`, 'PATCH', { body }),
+      resolve: (id, resolved) => write(`/api/comments/${encodeURIComponent(id)}/resolve`, 'PATCH', { resolved }),
+      remove: id => write(`/api/comments/${encodeURIComponent(id)}`, 'DELETE'),
+    },
+  }
+}
+```
+
+在 React 中用 `useMemo(() => createContentHost(scope), [scope])` 创建并传入 Provider。
+`scope` 应包含应用、租户、账号及权限上下文，例如 `app:tenant:user:permissionVersion`；
+它变化时内容实例会重建。切换前先处理未保存内容；同页不同权限实例使用不同 scope。
+
+| 服务 | 应用需返回什么 |
+| --- | --- |
+| `attachments.fetch(id)` | 附件原始 `Blob`，按当前用户鉴权 |
+| `uploadImage(file)` | `{ id, alt }`，`id` 为稳定附件 UUID |
+| `uploadFile(file)` | `{ id, filename, mimeType, size }`，大小单位为字节 |
+| `references.search(query, context)` | 当前用户可见的 `{ id, title }[]`，支持空查询 |
+| `references.resolve(id, label)` | `{ href, external? }`；不可见返回 `null`，页面降级为纯文本 |
+| `references.navigate(href)` | 可选；SPA 可在这里调用自己的 router |
+| `comments.list(resourceId)` | `{ items: CommentItem[] }`，回复放在父评论 `replies` 中 |
+| `comments.create(resourceId, body, parentId?, target?)` | 创建成功后 resolve；`target` 为导图的 `{ blockId, topicId }` |
+| `comments.update / resolve / remove` | 正文修改 / 解决状态 / 删除成功后 resolve；`update` 可选 |
+
+可选 `preferences.get(key) / set(key,value)` 存储展示偏好，例如代码主题键 `code-theme`。
+可选 `location.current() / subscribe(listener) / createLink({blockId,topicId})` 对接导图深链；
+`current()` 返回含 `mind` 和 `topic` 参数的 hash，`subscribe` 返回取消监听函数。
+
+**后端对应规则：** 上传返回稳定 ID，JSON 不存临时下载地址；列表和下载接口按用户鉴权。
+导图评论由后端把 `target` 写入 `anchor.prefix = 'mind:' + blockId`、`anchor.suffix = topicId`；
+普通行内评论则保存下面获取的文字锚点。编辑权限来自 `CommentItem.canEdit`，删除来自 `canDelete`，解决来自 `canResolve`。
+
+### 行内评论怎么接
+
+给编辑器传 `canComment`、`inlineComments={comments}`，并处理 `onRequestComment`。
+在用户点击评论入口时读取 `editor.current.getSelectionForAnchor()`，没有锚点就不创建。
+将 `{ ...anchor, seq: null }` 与评论正文交给应用的评论 API；保存后重新读取列表。
+
+阅读器传相同的 `inlineComments`，通过 `onMarkClick(id)` 打开讨论。
+编辑器用 `onInlineMarkClick(id)`；`activeCommentId` 控制当前讨论高亮。
+行内评论的输入面板由应用提供，主题讨论面板在导图内提供。
+
+## 工作表与 XLSX
+
+工作表编辑容器必须有明确高度。以下组件可直接挂到应用中，保存内容为 `WorkbookDocument`：
+
+```tsx
+import { useRef, useState } from 'react'
+import { ContentProvider } from 'wendang-react'
+import { SpreadsheetEditor, type SpreadsheetEditorHandle } from 'wendang-react/spreadsheet'
+import { SpreadsheetViewer } from 'wendang-react/spreadsheet/viewer'
+import { emptyWorkbook } from 'wendang/spreadsheet'
+import { WORKBOOK_SCHEMA_VERSION } from 'wendang/schema'
+import 'wendang-react/styles.css'
+
+export default function WorkbookExample() {
+  const editor = useRef<SpreadsheetEditorHandle>(null)
+  const [book, setBook] = useState(() => emptyWorkbook('sales'))
+  const [savedBook, setSavedBook] = useState(book)
+  const [message, setMessage] = useState('')
+  const [ready, setReady] = useState(false)
+  async function save() {
+    try {
+      if (!editor.current?.isReady()) return
+      const doc = await editor.current.prepareSnapshot()
+      localStorage.setItem('wendang:demo:workbook', JSON.stringify({ doc, schemaVersion: WORKBOOK_SCHEMA_VERSION }))
+      setSavedBook(doc)
+      setMessage('工作表已保存到本机')
+    } catch (error) { setMessage(String(error)) }
+  }
+  return <ContentProvider>
+    <button disabled={!ready} onClick={() => void save()}>保存工作表</button><p role="status">{message}</p>
+    <div style={{ height: 640 }}><SpreadsheetEditor ref={editor} value={book} onChange={setBook}
+      onReady={() => setReady(true)} onError={error => setMessage(error.message)} /></div>
+    <p>最近保存的工作表预览</p><SpreadsheetViewer value={savedBook} allowExport />
+  </ContentProvider>
+}
+```
+
+服务端保存时用 `WORKBOOK_SCHEMA_VERSION`，不要使用正文 `SCHEMA_VERSION`。
+阅读器显示最近保存的公式结果，不会重新计算。上面预览使用 `prepareSnapshot()` 的结果，
+避免公式计算尚未完成时就把编辑事件里的中间值拿去显示。
+
+XLSX 文件输入框得到 `File` 后调用导入；告警应先展示给用户，再替换当前工作表：
+
+```ts
+import type { SpreadsheetEditorHandle } from 'wendang-react/spreadsheet'
+
+export async function importWorkbook(file: File, editor: SpreadsheetEditorHandle) {
+  const { importXlsx } = await import('wendang-react/spreadsheet/xlsx')
+  const result = await importXlsx(file)
+  if (result.warnings.length && !window.confirm(result.warnings.join('\n') + '\n继续导入？')) return
+  editor.replace(result.doc)
+  return result.inspection
+}
+
+export async function downloadWorkbook(editor: SpreadsheetEditorHandle) {
+  const { exportXlsx } = await import('wendang-react/spreadsheet/xlsx')
+  const doc = await editor.prepareSnapshot()
+  const bytes = await exportXlsx(doc)
+  const url = URL.createObjectURL(new Blob([new Uint8Array(bytes)]))
+  const link = document.createElement('a')
+  link.href = url; link.download = '工作表.xlsx'; link.click()
+  setTimeout(() => URL.revokeObjectURL(url), 10000)
+}
+```
+
+支持 `.xlsx`，文件最大 5 MiB，展开后最大 20 MiB；不支持宏文件。
+图片、图表、绘图、透视等未转换内容会通过 `warnings` 提示。
+`replace()` 用于明确导入或切换内容，不要在每次 `onChange` 后调用。
+
+| 工作表接口 | 用途 |
+| --- | --- |
+| `value / onChange`、`disabled`、`theme` | 内容、编辑权限、可选主题 |
+| `onReady / onError` | 初始化成功与失败 |
+| `prepareSnapshot()` | 完成单元格编辑、等待计算并返回校验后的工作簿 |
+| `getSnapshot() / snapshot()`、`replace(doc)` | 立即取快照、替换工作簿 |
+| `isEditing() / finishEditing() / settleCalculation()` | 查询输入状态、完成输入、等待计算 |
+| `dispose()` | 主动销毁；正常组件卸载会自动清理 |
+
+`SpreadsheetViewer` 可传 `standalone` 填满容器、`allowExport` 显示导出、
+`exportSnapshot: () => Promise<{ title, doc }>` 提供当前有权导出的版本。
+
+## 思维导图
+
+```tsx
+import { useRef, useState } from 'react'
+import { ContentProvider } from 'wendang-react'
+import { MindMapEditor, type MindMapEditorHandle } from 'wendang-react/mindmap'
+import { MindMapViewer } from 'wendang-react/mindmap/viewer'
+import { createMindMap, readMindMap } from 'wendang/mindmap'
+import 'wendang-react/styles.css'
+
+export default function MindMapExample() {
+  const editor = useRef<MindMapEditorHandle>(null)
+  const [map, setMap] = useState(() => createMindMap('both'))
+  const [message, setMessage] = useState(''), [ready, setReady] = useState(false)
+  const model = readMindMap(map)
+  async function save() {
+    try {
+      if (!editor.current?.isReady()) return
+      localStorage.setItem('wendang:demo:mindmap', JSON.stringify(await editor.current.prepareSnapshot()))
+      setMessage('导图已保存到本机')
+    } catch (error) { setMessage(String(error)) }
+  }
+  return <ContentProvider>
+    <button disabled={!ready} onClick={() => void save()}>保存导图</button><p role="status">{message}</p>
+    <div style={{ height: 640 }}><MindMapEditor ref={editor} value={map} onChange={setMap} allowExport
+      onReady={() => setReady(true)} onError={error => setMessage(error.message)} /></div>
+    {model && <MindMapViewer value={model} />}
+  </ContentProvider>
+}
+```
+
+保存 `MindMapJson`，其中包含 `formatVersion`；从服务器加载后先用 `readMindMap` 检查，再传给 `value`。
+上面工作表和导图例子演示写入本机；恢复时读取相应 storage key、检查内容后初始化状态即可。
+
+点击主题选中，Tab 添加子主题，Enter 添加同级，F2 / 双击改名；Delete 删除，含子主题先确认。
+Shift / Ctrl / ⌘ 点击可多选，空白处拖动框选；拖动中实时显示命中，Esc 取消。
+空格或中键拖动平移，Ctrl / ⌘ + 滚轮缩放。分支可拖到目标或中心另一侧，操作支持撤销。
+
+| Props / 接口 | 用途 |
+| --- | --- |
+| `value / onChange`、`disabled`、`allowExport` | 导图 JSON、编辑权限、导出开关 |
+| `resourceId / canComment / openComments` | 讨论资源、发表评论权限、初始展开讨论 |
+| `saveStatus / showSaveHint` | 应用的真实保存状态；关闭默认保存提醒 |
+| `collabAwareness / viewState` | 在线用户状态、视口/折叠/选中状态 |
+| `onReady / onError / onCommentsChanged` | 就绪、失败、讨论更新 |
+| `prepareSnapshot() / getSnapshot()` | 保存快照 / 立即读取；主题输入未完成时先结束输入 |
+| `undo() / redo() / focus()` | 撤销、重做、聚焦 |
+
+更多菜单提供大纲、属性、讨论、导入；布局、配色和预览高度可在工具栏调整，分支线型在视图设置中。
+导出支持 PNG / SVG / Markdown / JSON。独立导图是快照编辑；`collabAwareness` 仅提供在线状态，不同步内容。
+正文内插入的导图随整篇文档保存。
+
+## 文档协同接入
+
+文档可以接收应用维护的 `Y.Doc` 和 `Awareness`，连接与认证由应用选择的 Yjs provider 提供。
+以下组件接收已建立连接的实例；切换资源时给组件设置不同 `key`，不要同时传 `value` 初始化内容。
+
+```tsx
+import { ContentProvider } from 'wendang-react'
+import { DocumentEditor } from 'wendang-react/document'
+import type { CollaborationDocument, Awareness } from 'wendang-react/bindings/yjs'
+import 'wendang-react/styles.css'
+
+export default function CollaborativeDocument({ doc, awareness, canEdit }: {
+  doc: CollaborationDocument; awareness: Awareness; canEdit: boolean
+}) {
+  return <ContentProvider>
+    <div style={{ padding: '0 56px' }}><DocumentEditor collabDoc={doc} collabAwareness={awareness}
+      disabled={!canEdit} onChange={(_value, meta) => { console.log(meta?.remote ? '收到远端更新' : '本地编辑') }} /></div>
+  </ContentProvider>
+}
+```
+
+正文使用 Y.Doc 的 `default` XmlFragment。服务端/协同 provider 负责初始化及持久化 Yjs 更新；
+不要对已同步文档再次 `setContent` 灌入初始 JSON。连接关闭、撤权、重连和卸载由应用管理。
+工作表与独立导图使用快照保存；它们不通过 `collabDoc` 同步。
+
+## 主题、按需导入和接入规范
+
+`ContentProvider` 支持 `theme="light" | "dark"`、`accent="#2f6feb"`、`host` 和 `unstyled`。
+每个 Provider 可使用不同主题；`unstyled` 需由应用提供颜色和排版变量。
+`allowExport` 默认关闭，控制导出和下载入口；后端仍需验证下载权限。
+
+| 入口 | 主要组件 / API |
+| --- | --- |
+| `wendang-react` | `ContentProvider`、宿主服务类型 |
+| `wendang-react/document` | `DocumentEditor`、ref 类型、`sameDocument`、定位工具 |
+| `wendang-react/document/viewer` | `DocumentViewer` |
+| `wendang-react/spreadsheet`、`spreadsheet/viewer` | 工作表编辑 / 阅读 |
+| `wendang-react/spreadsheet/xlsx` | `importXlsx / exportXlsx` |
+| `wendang-react/mindmap`、`mindmap/viewer` | 导图编辑 / 预览、`MindMapBlock` |
+| `wendang-react/bindings/yjs` | 协同字段常量及类型 |
+| `wendang-react/shared` | 宿主通用工具 |
+
+SSR / Next.js 中将交互编辑组件放入带 `'use client'` 的客户端组件；
+访问 localStorage、window、网络连接的初始化放在 effect 中。全局样式在应用根入口引入。
+同一实例编辑时保持 ref、host 和资源 key 稳定；只有明确切换内容或身份才重建。
+
+## 常见问题
+
+- **没有样式或工具条被裁掉：** 引入 `styles.css`，正文外留 56px；父级不要裁掉操作轨道。
+- **工作表或导图为空白：** 容器需有明确高度，如 `640px`；检查 `onError` 和浏览器网络。
+- **图片/文件无法上传或显示：** 接入 `host.attachments`，fetch 返回 Blob，上传返回稳定 UUID。
+- **无法选页面或发表评论：** 接入 `references / comments`，并传 `pageId / resourceId` 与 `canComment`。
+- **快照准备失败：** 完成上传、公式或主题输入，关闭未完成的插入对话框后重试；不要用空内容覆盖草稿。
+- **导出按钮没出现：** 显式传 `allowExport`，并确保后端允许导出该资源。
+- **切换账号还显示旧内容：** 更新 `host.scope` 并重新加载该账号有权访问的数据。
+
+## 联系与许可
+
+联系我们请发邮件：[yjmf@ztes.com](mailto:yjmf@ztes.com)。问题反馈：[Gitee Issues](https://gitee.com/ztes/wendang/issues)。
+
+采用随包附带的 [MIT 许可](LICENSE)。第三方声明见 `NOTICE.md` 与 `third-party-notices/`。

package/dist/bindings/yjs.js

@@ -0,0 +1,5 @@
+"use client";
+import { C } from "../chunks/extensions-B-CVVQhp.js";
+export {
+  C as COLLAB_FIELD
+};

package/dist/chunks/AnchoredPanel-D3nte06T.js

@@ -0,0 +1,68 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { useRef, useState, useLayoutEffect } from "react";
+import { createPortal } from "react-dom";
+import { a as useContentContext } from "./host-C-V688Rq.js";
+import { p as placeAnchoredPopover } from "./popover-placement-D3xVYdkt.js";
+import { u as useLayer, L as LayerProvider, p as placePanel } from "./index-Ii536CFG.js";
+function AnchoredPanel({ anchor, onClose, align = "start", prefer = "below", gap = 8, label, role = "dialog", className = "", portal: portalOverride, children, onKeyDown }) {
+  const context = useContentContext();
+  const portal = typeof portalOverride === "function" ? portalOverride() : portalOverride !== void 0 ? portalOverride : context.portal;
+  const panel = useRef(null);
+  const trigger = useRef(anchor);
+  trigger.current = anchor;
+  const layer = useLayer(trigger, panel, true, onClose);
+  const [position, setPosition] = useState(null);
+  useLayoutEffect(() => {
+    const measure = () => {
+      var _a;
+      const rect = anchor == null ? void 0 : anchor.getBoundingClientRect(), card = (_a = panel.current) == null ? void 0 : _a.getBoundingClientRect();
+      if (!rect || !card) return;
+      const placed = align === "end" ? placePanel({
+        trigger: rect,
+        panel: card,
+        position: prefer === "above" ? "tr" : "br",
+        gap,
+        viewport: { width: innerWidth, height: innerHeight }
+      }) : placeAnchoredPopover({
+        align,
+        prefer,
+        anchor: { left: rect.left, top: rect.top, width: rect.width, height: rect.height },
+        host: { left: 0, top: 0 },
+        card: { width: card.width, height: card.height },
+        bounds: { left: 0, top: 0, width: window.innerWidth, height: window.innerHeight },
+        gap
+      });
+      setPosition({ left: placed.left, top: placed.top });
+    };
+    measure();
+    const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(measure);
+    if (panel.current) observer == null ? void 0 : observer.observe(panel.current);
+    window.addEventListener("resize", measure);
+    window.addEventListener("scroll", measure, true);
+    return () => {
+      observer == null ? void 0 : observer.disconnect();
+      window.removeEventListener("resize", measure);
+      window.removeEventListener("scroll", measure, true);
+    };
+  }, [anchor, align, prefer, gap]);
+  if (!portal) return null;
+  return /* @__PURE__ */ jsx(LayerProvider, { layer, children: createPortal(/* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: panel,
+      className: `w-popover w-popover--flush${className ? ` ${className}` : ""}`,
+      role,
+      "aria-label": label,
+      onKeyDown,
+      onPointerDown: (event) => event.stopPropagation(),
+      onWheel: (event) => event.stopPropagation(),
+      onContextMenu: (event) => event.stopPropagation(),
+      style: { position: "fixed", left: (position == null ? void 0 : position.left) ?? -9999, top: (position == null ? void 0 : position.top) ?? -9999 },
+      children
+    }
+  ), portal) });
+}
+export {
+  AnchoredPanel as A
+};