@hamster-note/notes 2.0.0 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +205 -59
- package/dist/index.cjs +227 -57
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +42042 -22960
- package/dist/index.js.map +1 -1
- package/dist/lib/editor/HnnDataDrawer.d.ts +18 -0
- package/dist/lib/editor/HnnDataDrawer.d.ts.map +1 -0
- package/dist/lib/editor/HostReferenceUI.d.ts +22 -0
- package/dist/lib/editor/HostReferenceUI.d.ts.map +1 -0
- package/dist/lib/editor/MarkdownExport.d.ts +29 -0
- package/dist/lib/editor/MarkdownExport.d.ts.map +1 -0
- package/dist/lib/editor/NoteEditor.d.ts +19 -0
- package/dist/lib/editor/NoteEditor.d.ts.map +1 -0
- package/dist/lib/editor/NoteSaveStatus.d.ts +22 -0
- package/dist/lib/editor/NoteSaveStatus.d.ts.map +1 -0
- package/dist/lib/editor/blockMenu.d.ts +19 -0
- package/dist/lib/editor/blockMenu.d.ts.map +1 -0
- package/dist/lib/editor/blockReorder.d.ts +77 -0
- package/dist/lib/editor/blockReorder.d.ts.map +1 -0
- package/dist/lib/editor/hostReferenceInteractions.d.ts +34 -0
- package/dist/lib/editor/hostReferenceInteractions.d.ts.map +1 -0
- package/dist/lib/editor/hostReferences.d.ts +40 -0
- package/dist/lib/editor/hostReferences.d.ts.map +1 -0
- package/dist/lib/editor/nativeClipboard.d.ts +8 -0
- package/dist/lib/editor/nativeClipboard.d.ts.map +1 -0
- package/dist/lib/editor/pictureUpload.d.ts +27 -0
- package/dist/lib/editor/pictureUpload.d.ts.map +1 -0
- package/dist/lib/editor/session.d.ts +71 -0
- package/dist/lib/editor/session.d.ts.map +1 -0
- package/dist/lib/editor/sessionKey.d.ts +6 -0
- package/dist/lib/editor/sessionKey.d.ts.map +1 -0
- package/dist/lib/editor/types.d.ts +143 -0
- package/dist/lib/editor/types.d.ts.map +1 -0
- package/dist/lib/hnn/budgetedTransaction.d.ts +44 -0
- package/dist/lib/hnn/budgetedTransaction.d.ts.map +1 -0
- package/dist/lib/hnn/cardPayload.d.ts +48 -0
- package/dist/lib/hnn/cardPayload.d.ts.map +1 -0
- package/dist/lib/hnn/codec.d.ts +21 -0
- package/dist/lib/hnn/codec.d.ts.map +1 -0
- package/dist/lib/hnn/directoryEntries.d.ts +12 -0
- package/dist/lib/hnn/directoryEntries.d.ts.map +1 -0
- package/dist/lib/hnn/drawingPayload.d.ts +26 -0
- package/dist/lib/hnn/drawingPayload.d.ts.map +1 -0
- package/dist/lib/hnn/extensions.d.ts +50 -0
- package/dist/lib/hnn/extensions.d.ts.map +1 -0
- package/dist/lib/hnn/limits.d.ts +30 -0
- package/dist/lib/hnn/limits.d.ts.map +1 -0
- package/dist/lib/hnn/markdown.d.ts +29 -0
- package/dist/lib/hnn/markdown.d.ts.map +1 -0
- package/dist/lib/hnn/menuPopover.d.ts +46 -0
- package/dist/lib/hnn/menuPopover.d.ts.map +1 -0
- package/dist/lib/hnn/nodeId.d.ts +20 -0
- package/dist/lib/hnn/nodeId.d.ts.map +1 -0
- package/dist/lib/hnn/persistedStringBudget.d.ts +21 -0
- package/dist/lib/hnn/persistedStringBudget.d.ts.map +1 -0
- package/dist/lib/hnn/schema.d.ts +6 -0
- package/dist/lib/hnn/schema.d.ts.map +1 -0
- package/dist/lib/hnn/stringBytes.d.ts +29 -0
- package/dist/lib/hnn/stringBytes.d.ts.map +1 -0
- package/dist/lib/hnn/tableEdgeControls.d.ts +39 -0
- package/dist/lib/hnn/tableEdgeControls.d.ts.map +1 -0
- package/dist/lib/hnn/urlPolicy.d.ts +8 -0
- package/dist/lib/hnn/urlPolicy.d.ts.map +1 -0
- package/dist/lib/index.d.ts +6 -6
- package/dist/lib/index.d.ts.map +1 -1
- package/dist/styles.css +1 -1
- package/package.json +13 -8
- package/dist/lib/BlockActionMenu.d.ts +0 -55
- package/dist/lib/BlockActionMenu.d.ts.map +0 -1
- package/dist/lib/BlockActionMenuTypes.d.ts +0 -23
- package/dist/lib/BlockActionMenuTypes.d.ts.map +0 -1
- package/dist/lib/BottomBlockControls.d.ts +0 -17
- package/dist/lib/BottomBlockControls.d.ts.map +0 -1
- package/dist/lib/CardInspector.d.ts +0 -10
- package/dist/lib/CardInspector.d.ts.map +0 -1
- package/dist/lib/CardLinkOverlay.d.ts +0 -13
- package/dist/lib/CardLinkOverlay.d.ts.map +0 -1
- package/dist/lib/LinkMentionMenu.d.ts +0 -9
- package/dist/lib/LinkMentionMenu.d.ts.map +0 -1
- package/dist/lib/NoteBlockEditingControls.d.ts +0 -20
- package/dist/lib/NoteBlockEditingControls.d.ts.map +0 -1
- package/dist/lib/NoteBlockFocus.d.ts +0 -15
- package/dist/lib/NoteBlockFocus.d.ts.map +0 -1
- package/dist/lib/NoteCalloutBlock.d.ts +0 -10
- package/dist/lib/NoteCalloutBlock.d.ts.map +0 -1
- package/dist/lib/NoteCardBlock.d.ts +0 -10
- package/dist/lib/NoteCardBlock.d.ts.map +0 -1
- package/dist/lib/NoteChecklistBlock.d.ts +0 -10
- package/dist/lib/NoteChecklistBlock.d.ts.map +0 -1
- package/dist/lib/NoteCodeEditorBlock.d.ts +0 -10
- package/dist/lib/NoteCodeEditorBlock.d.ts.map +0 -1
- package/dist/lib/NoteCollapsibleBlock.d.ts +0 -10
- package/dist/lib/NoteCollapsibleBlock.d.ts.map +0 -1
- package/dist/lib/NoteContent.d.ts +0 -9
- package/dist/lib/NoteContent.d.ts.map +0 -1
- package/dist/lib/NoteContentBlocks.d.ts +0 -6
- package/dist/lib/NoteContentBlocks.d.ts.map +0 -1
- package/dist/lib/NoteContentEditing.d.ts +0 -58
- package/dist/lib/NoteContentEditing.d.ts.map +0 -1
- package/dist/lib/NoteDirectoryBlock.d.ts +0 -10
- package/dist/lib/NoteDirectoryBlock.d.ts.map +0 -1
- package/dist/lib/NoteDrawingBlock.d.ts +0 -10
- package/dist/lib/NoteDrawingBlock.d.ts.map +0 -1
- package/dist/lib/NoteFormulaBlock.d.ts +0 -10
- package/dist/lib/NoteFormulaBlock.d.ts.map +0 -1
- package/dist/lib/NoteListBlock.d.ts +0 -12
- package/dist/lib/NoteListBlock.d.ts.map +0 -1
- package/dist/lib/NoteParagraphBlock.d.ts +0 -12
- package/dist/lib/NoteParagraphBlock.d.ts.map +0 -1
- package/dist/lib/NotePictureBlock.d.ts +0 -10
- package/dist/lib/NotePictureBlock.d.ts.map +0 -1
- package/dist/lib/NoteQuoteBlock.d.ts +0 -11
- package/dist/lib/NoteQuoteBlock.d.ts.map +0 -1
- package/dist/lib/NoteTableBlock.d.ts +0 -5
- package/dist/lib/NoteTableBlock.d.ts.map +0 -1
- package/dist/lib/NoteTextBlockLayouts.d.ts +0 -27
- package/dist/lib/NoteTextBlockLayouts.d.ts.map +0 -1
- package/dist/lib/NoteTextBlocks.d.ts +0 -11
- package/dist/lib/NoteTextBlocks.d.ts.map +0 -1
- package/dist/lib/NoteTodoBlock.d.ts +0 -11
- package/dist/lib/NoteTodoBlock.d.ts.map +0 -1
- package/dist/lib/PictureUploadMenuItem.d.ts +0 -9
- package/dist/lib/PictureUploadMenuItem.d.ts.map +0 -1
- package/dist/lib/SelectionPopover.d.ts +0 -28
- package/dist/lib/SelectionPopover.d.ts.map +0 -1
- package/dist/lib/TableDragHandle.d.ts +0 -15
- package/dist/lib/TableDragHandle.d.ts.map +0 -1
- package/dist/lib/TableOperationMenu.d.ts +0 -16
- package/dist/lib/TableOperationMenu.d.ts.map +0 -1
- package/dist/lib/blockContainerDom.d.ts +0 -11
- package/dist/lib/blockContainerDom.d.ts.map +0 -1
- package/dist/lib/blockContainerMove.d.ts +0 -17
- package/dist/lib/blockContainerMove.d.ts.map +0 -1
- package/dist/lib/blockConversion.d.ts +0 -57
- package/dist/lib/blockConversion.d.ts.map +0 -1
- package/dist/lib/blockDowngrade.d.ts +0 -21
- package/dist/lib/blockDowngrade.d.ts.map +0 -1
- package/dist/lib/blockDragBindingKey.d.ts +0 -3
- package/dist/lib/blockDragBindingKey.d.ts.map +0 -1
- package/dist/lib/blockDragDesktop.d.ts +0 -13
- package/dist/lib/blockDragDesktop.d.ts.map +0 -1
- package/dist/lib/blockDragDom.d.ts +0 -24
- package/dist/lib/blockDragDom.d.ts.map +0 -1
- package/dist/lib/blockDragTarget.d.ts +0 -15
- package/dist/lib/blockDragTarget.d.ts.map +0 -1
- package/dist/lib/blockDragTouch.d.ts +0 -17
- package/dist/lib/blockDragTouch.d.ts.map +0 -1
- package/dist/lib/blockEditing.d.ts +0 -36
- package/dist/lib/blockEditing.d.ts.map +0 -1
- package/dist/lib/blockSourceConversion.d.ts +0 -41
- package/dist/lib/blockSourceConversion.d.ts.map +0 -1
- package/dist/lib/blockSourceInsertion.d.ts +0 -17
- package/dist/lib/blockSourceInsertion.d.ts.map +0 -1
- package/dist/lib/blockSourceMove.d.ts +0 -39
- package/dist/lib/blockSourceMove.d.ts.map +0 -1
- package/dist/lib/blockSourceOperations.d.ts +0 -37
- package/dist/lib/blockSourceOperations.d.ts.map +0 -1
- package/dist/lib/blockSourceSplit.d.ts +0 -4
- package/dist/lib/blockSourceSplit.d.ts.map +0 -1
- package/dist/lib/cardData.d.ts +0 -6
- package/dist/lib/cardData.d.ts.map +0 -1
- package/dist/lib/cardGeometry.d.ts +0 -14
- package/dist/lib/cardGeometry.d.ts.map +0 -1
- package/dist/lib/drawingData.d.ts +0 -37
- package/dist/lib/drawingData.d.ts.map +0 -1
- package/dist/lib/editableSelection.d.ts +0 -6
- package/dist/lib/editableSelection.d.ts.map +0 -1
- package/dist/lib/externalNoteDrag.d.ts +0 -55
- package/dist/lib/externalNoteDrag.d.ts.map +0 -1
- package/dist/lib/externalNoteDropTarget.d.ts +0 -11
- package/dist/lib/externalNoteDropTarget.d.ts.map +0 -1
- package/dist/lib/inlineFormulaRendering.d.ts +0 -37
- package/dist/lib/inlineFormulaRendering.d.ts.map +0 -1
- package/dist/lib/inlineMarkdownShortcut.d.ts +0 -75
- package/dist/lib/inlineMarkdownShortcut.d.ts.map +0 -1
- package/dist/lib/inlineSelectionFormatting.d.ts +0 -164
- package/dist/lib/inlineSelectionFormatting.d.ts.map +0 -1
- package/dist/lib/markdownShortcut.d.ts +0 -71
- package/dist/lib/markdownShortcut.d.ts.map +0 -1
- package/dist/lib/noteAtomicMutation.d.ts +0 -5
- package/dist/lib/noteAtomicMutation.d.ts.map +0 -1
- package/dist/lib/noteBoundarySplice.d.ts +0 -6
- package/dist/lib/noteBoundarySplice.d.ts.map +0 -1
- package/dist/lib/noteClipboardBlockCodec.d.ts +0 -4
- package/dist/lib/noteClipboardBlockCodec.d.ts.map +0 -1
- package/dist/lib/noteClipboardLimits.d.ts +0 -4
- package/dist/lib/noteClipboardLimits.d.ts.map +0 -1
- package/dist/lib/noteClipboardRegionSlice.d.ts +0 -4
- package/dist/lib/noteClipboardRegionSlice.d.ts.map +0 -1
- package/dist/lib/noteClipboardSlices.d.ts +0 -35
- package/dist/lib/noteClipboardSlices.d.ts.map +0 -1
- package/dist/lib/noteContentUndoRedo.d.ts +0 -34
- package/dist/lib/noteContentUndoRedo.d.ts.map +0 -1
- package/dist/lib/noteId.d.ts +0 -3
- package/dist/lib/noteId.d.ts.map +0 -1
- package/dist/lib/noteNestedMutation.d.ts +0 -7
- package/dist/lib/noteNestedMutation.d.ts.map +0 -1
- package/dist/lib/notePointerSelection.d.ts +0 -6
- package/dist/lib/notePointerSelection.d.ts.map +0 -1
- package/dist/lib/noteRegionCodec.d.ts +0 -9
- package/dist/lib/noteRegionCodec.d.ts.map +0 -1
- package/dist/lib/noteSelectAll.d.ts +0 -2
- package/dist/lib/noteSelectAll.d.ts.map +0 -1
- package/dist/lib/noteSelectionRestore.d.ts +0 -14
- package/dist/lib/noteSelectionRestore.d.ts.map +0 -1
- package/dist/lib/noteSnapshotMutation.d.ts +0 -8
- package/dist/lib/noteSnapshotMutation.d.ts.map +0 -1
- package/dist/lib/noteStructuredClipboard.d.ts +0 -17
- package/dist/lib/noteStructuredClipboard.d.ts.map +0 -1
- package/dist/lib/noteStructuredPaste.d.ts +0 -10
- package/dist/lib/noteStructuredPaste.d.ts.map +0 -1
- package/dist/lib/noteStructuredTail.d.ts +0 -3
- package/dist/lib/noteStructuredTail.d.ts.map +0 -1
- package/dist/lib/noteTextFlow.d.ts +0 -23
- package/dist/lib/noteTextFlow.d.ts.map +0 -1
- package/dist/lib/noteTextOffset.d.ts +0 -4
- package/dist/lib/noteTextOffset.d.ts.map +0 -1
- package/dist/lib/noteTransferReplacement.d.ts +0 -10
- package/dist/lib/noteTransferReplacement.d.ts.map +0 -1
- package/dist/lib/quoteLineEditing.d.ts +0 -5
- package/dist/lib/quoteLineEditing.d.ts.map +0 -1
- package/dist/lib/restrictedHtml.d.ts +0 -7
- package/dist/lib/restrictedHtml.d.ts.map +0 -1
- package/dist/lib/syntaxHighlight.d.ts +0 -9
- package/dist/lib/syntaxHighlight.d.ts.map +0 -1
- package/dist/lib/tableDragPreview.d.ts +0 -15
- package/dist/lib/tableDragPreview.d.ts.map +0 -1
- package/dist/lib/tableDragTarget.d.ts +0 -13
- package/dist/lib/tableDragTarget.d.ts.map +0 -1
- package/dist/lib/tableEditing.d.ts +0 -35
- package/dist/lib/tableEditing.d.ts.map +0 -1
- package/dist/lib/tableKeyboardNavigation.d.ts +0 -14
- package/dist/lib/tableKeyboardNavigation.d.ts.map +0 -1
- package/dist/lib/tableMoveFocus.d.ts +0 -11
- package/dist/lib/tableMoveFocus.d.ts.map +0 -1
- package/dist/lib/types.d.ts +0 -302
- package/dist/lib/types.d.ts.map +0 -1
- package/dist/lib/useBlockDrag.d.ts +0 -11
- package/dist/lib/useBlockDrag.d.ts.map +0 -1
- package/dist/lib/useBlockEditing.d.ts +0 -9
- package/dist/lib/useBlockEditing.d.ts.map +0 -1
- package/dist/lib/useDraggedTouchClickSuppression.d.ts +0 -7
- package/dist/lib/useDraggedTouchClickSuppression.d.ts.map +0 -1
- package/dist/lib/useExternalNoteDrag.d.ts +0 -15
- package/dist/lib/useExternalNoteDrag.d.ts.map +0 -1
- package/dist/lib/useTableMoveFocus.d.ts +0 -11
- package/dist/lib/useTableMoveFocus.d.ts.map +0 -1
- package/dist/lib/useTableOperationMenus.d.ts +0 -19
- package/dist/lib/useTableOperationMenus.d.ts.map +0 -1
- package/dist/lib/utils.d.ts +0 -10
- package/dist/lib/utils.d.ts.map +0 -1
package/README.md
CHANGED
|
@@ -1,13 +1,17 @@
|
|
|
1
1
|
# @hamster-note/notes
|
|
2
2
|
|
|
3
|
-
一个基于 React 19 和 Vite
|
|
3
|
+
一个基于 React 19 和 Vite 的笔记组件库,编辑内核为 TipTap/ProseMirror,持久化格式为 HNN,并支持 GFM + HamsterNote 围栏的 Markdown 导入/导出。包含可本地预览的 Demo 页面,以及基于 Git Tag 的 GitHub Actions 发布流程。
|
|
4
|
+
|
|
5
|
+
**[在线 Demo](https://hamsternote.github.io/notes/)**
|
|
4
6
|
|
|
5
7
|
## 特性
|
|
6
8
|
|
|
7
9
|
- React 19 组件库入口,包名为 `@hamster-note/notes`
|
|
10
|
+
- 以 TipTap/ProseMirror 为唯一文档与交互内核:原生选区、剪贴板、撤销/重做
|
|
11
|
+
- HNN 持久化:`{ schemaVersion: 1, data: <ProseMirror JSON> }`,严格校验、无损往返
|
|
12
|
+
- 封闭 schema:不向宿主开放自定义扩展/schema 注入
|
|
8
13
|
- 使用 Vite 构建库产物和 Demo 页面
|
|
9
|
-
- TypeScript 6 beta
|
|
10
|
-
- ESLint + Prettier 代码质量与格式化
|
|
14
|
+
- TypeScript 6 beta 严格类型检查,ESLint + Prettier
|
|
11
15
|
- 局域网可访问的本地开发服务器,端口 `9235`
|
|
12
16
|
- GitHub CI 校验 + Tag 驱动 npm 发布
|
|
13
17
|
|
|
@@ -29,84 +33,226 @@ yarn build
|
|
|
29
33
|
- `yarn build:lib` 生成组件库产物到 `dist/`
|
|
30
34
|
- `yarn build:demo` 生成 Demo 静态站点到 `dist/demo/`
|
|
31
35
|
|
|
32
|
-
##
|
|
36
|
+
## 公共 API
|
|
33
37
|
|
|
34
|
-
|
|
35
|
-
|
|
38
|
+
> ⚠️ **不兼容变更**:本版本整体替换了旧编辑内核。旧的 `NoteContent`、`NoteBlock` 等块模型 API、受限 HTML 渲染、自研 DOM 选区与专有剪贴板 MIME 已从包入口移除,且**不提供旧格式迁移或兼容层**。
|
|
39
|
+
|
|
40
|
+
包入口仅导出以下内容:
|
|
41
|
+
|
|
42
|
+
- 组件:`NoteEditor`、`NoteSaveStatus`、`MarkdownExport`
|
|
43
|
+
- 编解码:`decodeHnn`、`encodeHnn`、`HnnCodecError`、`importMarkdown`、`exportMarkdown`
|
|
44
|
+
- 类型:新组件 props、HNN/Markdown codec 类型,以及宿主回调契约(`NoteSave*`、`InitialLoadError*`、`EditorSession*`、`PictureUpload*`、`HostReference*`、`HostCandidate*` 等)
|
|
45
|
+
|
|
46
|
+
```ts
|
|
47
|
+
import {
|
|
48
|
+
NoteEditor,
|
|
49
|
+
decodeHnn,
|
|
50
|
+
encodeHnn,
|
|
51
|
+
HnnCodecError,
|
|
52
|
+
importMarkdown,
|
|
53
|
+
exportMarkdown,
|
|
54
|
+
type HnnDocument,
|
|
55
|
+
} from "@hamster-note/notes"
|
|
36
56
|
import "@hamster-note/notes/styles.css"
|
|
37
57
|
```
|
|
38
58
|
|
|
39
|
-
|
|
59
|
+
### 装载与编辑
|
|
60
|
+
|
|
61
|
+
`NoteEditor` 由 `documentId` 与 `loadKey` 共同定义一次编辑会话。`initialDocument` 的类型是 `unknown`:宿主只需传入 HNN 外壳(`{ schemaVersion: 1, data }`),**严格校验由库自身完成**,无需(也不应)在宿主侧预先构造内部文档。
|
|
40
62
|
|
|
41
63
|
```tsx
|
|
42
|
-
import "@hamster-note/notes
|
|
64
|
+
import { NoteEditor, type HnnDocument, type NoteSave } from "@hamster-note/notes"
|
|
65
|
+
import "@hamster-note/notes/styles.css"
|
|
66
|
+
|
|
67
|
+
// 合法最小 HNN:schemaVersion 固定为 1,data 为 ProseMirror JSON;持久节点带合法 UUID nodeId。
|
|
68
|
+
const document: HnnDocument = {
|
|
69
|
+
schemaVersion: 1,
|
|
70
|
+
data: {
|
|
71
|
+
type: "doc",
|
|
72
|
+
content: [
|
|
73
|
+
{
|
|
74
|
+
type: "paragraph",
|
|
75
|
+
attrs: { nodeId: "123e4567-e89b-42d3-a456-426614174000" },
|
|
76
|
+
content: [{ type: "text", text: "你好" }],
|
|
77
|
+
},
|
|
78
|
+
],
|
|
79
|
+
},
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
function Editor({
|
|
83
|
+
documentId,
|
|
84
|
+
loadKey,
|
|
85
|
+
revision,
|
|
86
|
+
onSave,
|
|
87
|
+
}: {
|
|
88
|
+
documentId: string
|
|
89
|
+
loadKey: string | number
|
|
90
|
+
revision?: string
|
|
91
|
+
onSave: NoteSave
|
|
92
|
+
}) {
|
|
93
|
+
return (
|
|
94
|
+
<NoteEditor
|
|
95
|
+
documentId={documentId}
|
|
96
|
+
loadKey={loadKey}
|
|
97
|
+
initialDocument={document}
|
|
98
|
+
initialRevision={revision}
|
|
99
|
+
onSave={onSave}
|
|
100
|
+
onChange={(snapshot) => {
|
|
101
|
+
// 每次文档变化都会收到完整 HNN 快照(仅通知,不代表已保存)
|
|
102
|
+
}}
|
|
103
|
+
onInitialLoadError={(error, { documentId, loadKey }) => {
|
|
104
|
+
// 初始 HNN 严格校验失败:库不会用损坏输入构造降级会话
|
|
105
|
+
}}
|
|
106
|
+
theme="light"
|
|
107
|
+
/>
|
|
108
|
+
)
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
从任意外部输入得到可传入的 HNN:
|
|
113
|
+
|
|
114
|
+
```ts
|
|
115
|
+
import { decodeHnn, encodeHnn } from "@hamster-note/notes"
|
|
116
|
+
|
|
117
|
+
// decodeHnn 是公开编解码函数,返回经严格校验的 ProseMirror doc,而不是 HNN 外壳;
|
|
118
|
+
// 需要可持久化 / 可装载的 HNN 时,必须再 encode 一次:
|
|
119
|
+
const hnn = encodeHnn(decodeHnn(unknownInput)) // 类型为 HnnDocument,可传 NoteEditor.initialDocument
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
会话语义:
|
|
123
|
+
|
|
124
|
+
- 同一 `documentId` 与 `loadKey` 下,后续 `initialDocument` **与 `initialRevision`** 的变化都会被忽略,不会覆盖用户当前编辑。
|
|
125
|
+
- 任一 `documentId` 或 `loadKey` 变化,都会以当次已验证 HNN 重建整个会话(文档、选区、撤销历史、baseline 全部重置)。
|
|
126
|
+
- 若新 `documentId`/`loadKey` 对应的初始 HNN 校验失败,**当前会话保持不变**(不会切到损坏文档),错误经 `onInitialLoadError` 通知宿主。
|
|
127
|
+
- 撤销/重做由库内封闭装配的 history 提供,宿主不能注入或替换 schema/extensions/history。
|
|
128
|
+
|
|
129
|
+
### 保存(宿主 CAS)
|
|
130
|
+
|
|
131
|
+
```ts
|
|
132
|
+
import type { NoteSave } from "@hamster-note/notes"
|
|
133
|
+
|
|
134
|
+
const onSave: NoteSave = async (snapshot, { documentId, baseRevision, signal }) => {
|
|
135
|
+
// 宿主必须以 documentId + baseRevision 实施 CAS,并对真实存储负责。
|
|
136
|
+
const result = await host.writeIfUnchanged(documentId, snapshot, baseRevision)
|
|
137
|
+
return result.conflict ? { kind: "conflict" } : { kind: "saved", revision: result.revision }
|
|
138
|
+
}
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
- 保存回调签名:`onSave(snapshot, { documentId, baseRevision?, signal })`,返回 `{ kind: "saved", revision? }` 或 `{ kind: "conflict" }`。
|
|
142
|
+
- 每个会话同时最多一个在途保存(单飞)。
|
|
143
|
+
- `signal`/abort **只隔离库内状态**,不能替代宿主的原子存储事务;即使宿主忽略了 abort,陈旧请求仍可能落盘,因此必须靠宿主的 CAS 防御。
|
|
144
|
+
- 冲突不自动合并:库只暴露冲突态,由宿主以新的 `initialDocument` + 新 `loadKey` 重载远端,或按自身策略重试本地保存。
|
|
145
|
+
- Demo 宿主的 `hostStore` 演示了一个真实原子实现:每次保存与「模拟另一客户端写入」都在**同一个持久化 key 的排他 Web Lock 内**完成 read→compare→write;`saveWithCas`/`overwriteExternal` 因此是异步 API。
|
|
146
|
+
- Web Locks 仅在**安全上下文(HTTPS 或 localhost)**且浏览器支持时可用。若运行环境不提供 Web Locks,宿主**fail closed**:抛出显式错误且**绝不写入**,绝不降级为「read-check-write」这种非原子的伪 CAS。在线 Demo 即为 HTTPS/localhost 场景。
|
|
147
|
+
|
|
148
|
+
### HNN 文档格式
|
|
149
|
+
|
|
150
|
+
```ts
|
|
151
|
+
import { decodeHnn, encodeHnn, HnnCodecError } from "@hamster-note/notes"
|
|
152
|
+
|
|
153
|
+
try {
|
|
154
|
+
decodeHnn(unknownInput) // 严格校验
|
|
155
|
+
} catch (error) {
|
|
156
|
+
if (error instanceof HnnCodecError) {
|
|
157
|
+
// 未知 schemaVersion / 未知节点 / 未知 mark / 非法 attrs / 结构非法 一律硬错误
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
- 完整 HNN v1 外壳的 UTF-8 编码上限为 **512 KiB**;此外还受树深度、节点总数、单 attr 大小等限制。
|
|
163
|
+
- 遇到未知 `schemaVersion`、未知节点类型、未知 mark、非法 attrs 或不满足 schema 的结构,一律抛出 `HnnCodecError`,**不提供降级或静默覆盖**;失败时不产生可保存的替代文档,原文保持不变。
|
|
164
|
+
|
|
165
|
+
### Markdown 导入 / 导出
|
|
166
|
+
|
|
167
|
+
```ts
|
|
168
|
+
import { importMarkdown, exportMarkdown } from "@hamster-note/notes"
|
|
169
|
+
|
|
170
|
+
const imported = importMarkdown(markdownText)
|
|
171
|
+
if (imported.document !== undefined) {
|
|
172
|
+
// 转成 HNN 可编辑文档;default 保存始终是 HNN
|
|
173
|
+
const hnn = imported.document
|
|
174
|
+
} else {
|
|
175
|
+
// imported.failure: "input-too-large" | "conversion-failed"
|
|
176
|
+
// 导入失败绝不替换源 Markdown;调用方保留原始输入
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
const exported = exportMarkdown(hnnDocument)
|
|
180
|
+
// exported.markdown 为 GFM + HamsterNote 围栏方言
|
|
181
|
+
// exported.diagnostics 列出无法无损表达而发生的降级;诊断非空时必须由用户显式确认后才交给宿主写出
|
|
43
182
|
```
|
|
44
183
|
|
|
45
|
-
|
|
184
|
+
- 导入:Markdown → ProseMirror doc;导出为可选能力,无法无损表达时**必须产出降级诊断**,不得静默降级。
|
|
185
|
+
- 保存默认始终写 HNN,Markdown 导出仅在用户显式触发并经诊断确认后调用宿主写出回调。
|
|
46
186
|
|
|
47
|
-
|
|
187
|
+
### 图片上传(仅 `picture`)
|
|
48
188
|
|
|
49
189
|
```tsx
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
190
|
+
<NoteEditor
|
|
191
|
+
documentId={documentId}
|
|
192
|
+
loadKey={loadKey}
|
|
193
|
+
initialDocument={document}
|
|
194
|
+
onPictureUpload={async (file, { uploadId, attempt, signal }) => {
|
|
195
|
+
// 宿主必须按 uploadId 幂等;retry 时 uploadId 不变、attempt 递增
|
|
196
|
+
const uploaded = await host.uploadImage(file, { uploadId, attempt, signal })
|
|
197
|
+
return { src: uploaded.httpsUrl, alt: uploaded.alt } // src 必须是 http/https
|
|
198
|
+
}}
|
|
199
|
+
/>
|
|
200
|
+
```
|
|
56
201
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
onTitleChange={undoRedo.setTitle}
|
|
81
|
-
onSummaryChange={undoRedo.setSummary}
|
|
82
|
-
onBlocksChange={undoRedo.setBlocks}
|
|
83
|
-
onNoteTransaction={({ snapshot }) => undoRedo.commitTransaction(snapshot)}
|
|
84
|
-
/>
|
|
85
|
-
</>
|
|
86
|
-
)
|
|
202
|
+
- 每个文件一个稳定 `uploadId`,首次 `attempt` 为 1,retry 只递增 `attempt`;宿主应据此去重。
|
|
203
|
+
- 成功时宿主返回可持久化的 `http`/`https` `src` 与可选 `alt`;库仅以一个 transaction 写入图片。
|
|
204
|
+
- 上传临时态、文件、`uploadId`、`attempt` 均为内存/DOM 桥状态,**绝不进入 HNN**;失败可重试或取消。
|
|
205
|
+
|
|
206
|
+
### 宿主引用(mention / resource / externalItem)
|
|
207
|
+
|
|
208
|
+
文档只持久 `resourceId` 与展示 `name`(绝不写入解析内容),真实内容由宿主在运行时解析:
|
|
209
|
+
|
|
210
|
+
```tsx
|
|
211
|
+
<NoteEditor
|
|
212
|
+
documentId={documentId}
|
|
213
|
+
loadKey={loadKey}
|
|
214
|
+
initialDocument={document}
|
|
215
|
+
onReferenceCandidates={async (kind, query, { documentId, signal }) =>
|
|
216
|
+
host.searchReferences(kind, query, { documentId, signal }) // [{ resourceId, name }]
|
|
217
|
+
}
|
|
218
|
+
onReferenceActivate={(reference, { documentId, signal }) => {
|
|
219
|
+
host.openReference(reference, { documentId, signal }) // 库不会自行跳转
|
|
220
|
+
}}
|
|
221
|
+
onReferenceResolve={async ({ kind, resourceId }, { documentId, signal }) =>
|
|
222
|
+
host.resolveReference(kind, resourceId, { documentId, signal }) // { label, description? } | null
|
|
223
|
+
}
|
|
224
|
+
/>
|
|
87
225
|
```
|
|
88
226
|
|
|
89
|
-
|
|
227
|
+
- 解析结果只用于运行时占位展示(`loading`/`resolved`/`missing`/`error`),**不写入文档、不接受 HTML**。
|
|
228
|
+
- 无回调时受控为空/缺失占位,不破坏文档;文档/baseline/history 不受影响。
|
|
229
|
+
|
|
230
|
+
### 主题与公式样式
|
|
90
231
|
|
|
91
|
-
|
|
232
|
+
```tsx
|
|
233
|
+
<NoteEditor ... theme="dark" />
|
|
234
|
+
```
|
|
92
235
|
|
|
93
|
-
|
|
236
|
+
`theme` 仅切换 `hn-*` token 修饰类。公式渲染所需的 KaTeX 样式按需导入:
|
|
94
237
|
|
|
95
|
-
|
|
238
|
+
```tsx
|
|
239
|
+
import "@hamster-note/notes/formula.css"
|
|
240
|
+
```
|
|
96
241
|
|
|
97
|
-
|
|
98
|
-
- 仅涉及正文的连续修改会降级为一次 `onBlocksChange` 调用。
|
|
99
|
-
- 单一区域编辑继续使用 `onTitleChange`、`onSummaryChange` 或 `onBlocksChange`。
|
|
242
|
+
## Demo
|
|
100
243
|
|
|
101
|
-
|
|
244
|
+
### 在线 Demo
|
|
102
245
|
|
|
103
|
-
|
|
246
|
+
访问 [https://hamsternote.github.io/notes/](https://hamsternote.github.io/notes/) 查看在线演示。
|
|
104
247
|
|
|
105
|
-
|
|
106
|
-
- `text/html`
|
|
107
|
-
- `application/x-hamsternote-fragment+json`
|
|
248
|
+
### 本地运行 Demo
|
|
108
249
|
|
|
109
|
-
|
|
250
|
+
```bash
|
|
251
|
+
yarn install
|
|
252
|
+
yarn dev
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
默认会在 `0.0.0.0:9235` 启动 Demo 页面。
|
|
110
256
|
|
|
111
257
|
## 发布规则
|
|
112
258
|
|