@4399ywkf/editor 0.6.0 → 0.8.0

package/dist/doc.d.ts

@@ -1,8 +1,12 @@
 import * as react from 'react';
 import { ReactNode, RefObject, useEffect, HTMLAttributes } from 'react';
 import { JSONContent, Editor, NodeWithPos, Extension as Extension$1, Node as Node$1 } from '@tiptap/react';
-import { Extensions, Extension } from '@tiptap/core';
+import * as _tiptap_core from '@tiptap/core';
+import { Extensions, JSONContent as JSONContent$1, Extension } from '@tiptap/core';
 import { Doc } from 'yjs';
+import { C as ContentFormat, a as CodeBlockOptions, b as CodeHighlighter } from './code-types-Dqmit3xx.js';
+export { c as CodeBlockAttrs, d as CodeGroupAttrs, H as HighlightResult, e as HighlightToken, S as ShikiTheme } from './code-types-Dqmit3xx.js';
+import { CodeBlockOptions as CodeBlockOptions$1 } from '@tiptap/extension-code-block';
 import { UseFloatingOptions, UseDismissProps, AutoUpdateOptions } from '@floating-ui/react';
 import { Selection, Transaction } from '@tiptap/pm/state';
 import { Node } from '@tiptap/pm/model';
@@ -10,6 +14,7 @@ import { B as ButtonProps } from './button-CWX5Uuj-.js';
 export { a as Button } from './button-CWX5Uuj-.js';
 import * as PopoverPrimitive from '@radix-ui/react-popover';
 import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu';
+import 'shiki';
 
 /**
  * 包消费者通过 `<EditorConfigProvider>` 注入业务侧能力。
@@ -134,6 +139,18 @@ interface NotionEditorProps {
      * 协同模式下 yjs Doc 接管内容，传入会被忽略以免跟 sync 冲突。
      */
     content?: string | JSONContent;
+    /**
+     * `content` 的格式。不传时沿用旧规则：对象按 JSON、字符串按 HTML。
+     * `"markdown"` 时字符串经 Markdown 解析（支持 `::: code-group` 代码分组）；
+     * `"json"` 只接受对象，不会去解析 JSON 文本。格式与内容类型不匹配时
+     * console.error 一条 `[editor]` 信息并保留当前文档不动。
+     */
+    contentFormat?: ContentFormat;
+    /**
+     * 代码块高亮配置（Shiki 主题 / 语言别名 / 额外语言注册）。默认 github-light /
+     * github-dark 随 `.dark` 切换，语言按需加载，无需配置即可用。
+     */
+    codeBlock?: CodeBlockOptions;
     /**
      * 只读模式：用于展示文章内容。设为 true 时编辑器不可编辑（editable:false），
      * 且隐藏所有编辑态 UI（头部工具栏、浮动工具栏、拖拽手柄、slash/mention/emoji
@@ -172,6 +189,10 @@ interface EditorProviderProps {
     placeholder?: string;
     /** 本地编辑模式下的初始/同步内容，详见 NotionEditorProps.content */
     content?: string | JSONContent;
+    /** 内容格式，详见 NotionEditorProps.contentFormat */
+    contentFormat?: ContentFormat;
+    /** 代码块高亮配置，详见 NotionEditorProps.codeBlock */
+    codeBlock?: CodeBlockOptions;
     /** 只读模式，详见 NotionEditorProps.readOnly */
     readOnly?: boolean;
     /** 隐藏包内置顶部工具条，详见 NotionEditorProps.hideHeader */
@@ -211,13 +232,17 @@ declare function EditorProvider(props: EditorProviderProps): react.JSX.Element;
 /**
  * Full editor with all necessary providers, ready to use with just a room ID
  */
-declare function NotionEditor({ room, placeholder, content, readOnly, hideHeader, onEditorReady, extensions, }: NotionEditorProps): react.JSX.Element;
+declare function NotionEditor({ room, placeholder, content, contentFormat, codeBlock, readOnly, hideHeader, onEditorReady, extensions, }: NotionEditorProps): react.JSX.Element;
 /**
  * Internal component that handles the editor loading state
  */
-declare function NotionEditorContent({ placeholder, content, readOnly, hideHeader, onEditorReady, extensions, }: {
+declare function NotionEditorContent({ placeholder, content, contentFormat, codeBlock, readOnly, hideHeader, onEditorReady, extensions, }: {
     placeholder?: string;
     content?: string | JSONContent;
+    /** 内容格式，详见 NotionEditorProps.contentFormat */
+    contentFormat?: ContentFormat;
+    /** 代码块高亮配置，详见 NotionEditorProps.codeBlock */
+    codeBlock?: CodeBlockOptions;
     readOnly?: boolean;
     hideHeader?: boolean;
     onEditorReady?: (editor: Editor) => void;
@@ -231,8 +256,12 @@ declare function NotionEditorContent({ placeholder, content, readOnly, hideHeade
     extensions?: Extensions;
 }): react.JSX.Element;
 interface ArticleViewerProps {
-    /** 文章内容（HTML 字符串或 tiptap JSONContent），通常由 HTTP 接口拉取后传入 */
+    /** 文章内容（HTML 字符串、Markdown 字符串或 tiptap JSONContent），通常由 HTTP 接口拉取后传入 */
     content?: string | JSONContent;
+    /** 内容格式，详见 NotionEditorProps.contentFormat */
+    contentFormat?: ContentFormat;
+    /** 代码块高亮配置，详见 NotionEditorProps.codeBlock */
+    codeBlock?: CodeBlockOptions;
     /** 空内容时的占位文案，默认空（viewer 一般不显示占位） */
     placeholder?: string;
 }
@@ -246,7 +275,85 @@ interface ArticleViewerProps {
  *
  * 用法：<ArticleViewer content={articleContent} />
  */
-declare function ArticleViewer({ content, placeholder }: ArticleViewerProps): react.JSX.Element;
+declare function ArticleViewer({ content, contentFormat, codeBlock, placeholder }: ArticleViewerProps): react.JSX.Element;
+
+/** 只用到 Editor 的这几个面，避免把 @tiptap/core 的 Editor 类型绑死在签名里 */
+interface EditorLike {
+    getJSON(): JSONContent$1;
+    extensionManager: {
+        extensions: Extensions;
+    };
+    storage: object;
+}
+type ParsedContent = {
+    ok: true;
+    json: JSONContent$1 | null;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * 把任意输入规范成 Tiptap JSON。`json: null` 表示"没有内容"（undefined / null / 空串），
+ * 调用方按"不设置内容"处理。
+ */
+declare function parseEditorContent(content: unknown, format: ContentFormat | undefined, extensions: Extensions): ParsedContent;
+declare function serializeEditorMarkdown(json: JSONContent$1, extensions: Extensions): string;
+/**
+ * `editor.getMarkdown()` 的类型安全封装。那个方法来自 @tiptap/markdown 的模块扩充，
+ * 本包的 d.ts 不会把扩充带给消费方；用这个函数就不需要额外引 @tiptap/markdown 的类型。
+ * 优先用编辑器自己的 MarkdownManager（同一套 marked 实例），没有时按扩展集临时建一个。
+ */
+declare function getEditorMarkdown(editor: EditorLike): string;
+interface RenderHighlightedHTMLOptions extends CodeBlockOptions {
+    /** 传 Editor 时可省略；传 JSON 时必填 */
+    extensions?: Extensions;
+    /** 复用已有服务（传 Editor 时默认取编辑器里的那份） */
+    highlighter?: CodeHighlighter;
+    /** 主题：`"light"` / `"dark"` 走 shikiTheme 配置，其它字符串当 Shiki 主题名 */
+    theme?: "light" | "dark" | (string & {});
+}
+/**
+ * 导出调用时刻的文档快照为静态高亮 HTML：先取 JSON（之后的编辑不会混进来），
+ * 每个代码块经 Shiki 输出 token span，再按文档顺序替换语义 HTML 里的 `<pre>…</pre>`。
+ * 分组保留 `<div data-code-group>` 与每个 `<pre>` 的 data-language / data-label，
+ * 所有标签的代码都在、都可见 —— 不嵌脚本，不含 Decoration span 或按钮。
+ */
+declare function renderHighlightedHTML(source: EditorLike | JSONContent$1, options?: RenderHighlightedHTMLOptions): Promise<string>;
+
+type CodeBlockSchemaOptions = CodeBlockOptions$1 & CodeBlockOptions;
+
+declare const CodeBlockExtension: _tiptap_core.Node<CodeBlockSchemaOptions, any>;
+
+declare const CodeGroupExtension: _tiptap_core.Node<any, any>;
+
+declare const CalloutExtension: _tiptap_core.Node<any, any>;
+
+declare const DetailsExtension: _tiptap_core.Node<any, any>;
+
+/**
+ * 折叠块 / 提示框 / API 参数节点的公共类型。只有类型与常量，没有运行时依赖。
+ */
+declare const CALLOUT_TYPES: readonly ["info", "tip", "warning", "danger"];
+type CalloutType = (typeof CALLOUT_TYPES)[number];
+interface CalloutAttrs {
+    id?: string | null;
+    type: CalloutType;
+    title: string | null;
+}
+interface DetailsAttrs {
+    id?: string | null;
+    title: string | null;
+}
+interface ApiParamAttrs {
+    id?: string | null;
+    name: string;
+    type: string | null;
+    required: boolean;
+    default: string | null;
+    summary: string | null;
+}
+
+declare const ApiParamExtension: _tiptap_core.Node<any, any>;
 
 type CollabContextValue = {
     provider: CollabProviderLike | null;
@@ -1096,4 +1203,4 @@ declare const MediaUploadButton: react.ForwardRefExoticComponent<MediaUploadButt
  */
 declare function pickFile(accept: string, multiple?: boolean): Promise<File[]>;
 
-export { ArticleViewer, type ArticleViewerProps, Audio, ButtonProps, CollabContext, type CollabContextValue, CollabProvider, type CollabProviderLike, Column, type ColumnLayout, Columns, DEFAULT_MAX_FILE_SIZES, DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, type EditorCollabConfig, type EditorConfig, EditorConfigProvider, type EditorConfigProviderProps, EditorContentArea, type EditorProviderProps, type EditorUploadConfig, type EditorUserConfig, FileAttachment, type FileAttachmentAttrs, FloatingElement, HIDE_FLOATING_META, LoadingSpinner, MAC_SYMBOLS, MAX_FILE_SIZE, type MediaKind, type MediaKindForButton, MediaUploadButton, type MediaUploadButtonProps, MediaUploadPlaceholder, NotionEditor, NotionEditorContent, EditorProvider as NotionEditorInner, type NotionEditorProps, type OverflowPosition, PasteDropMedia, type PasteDropMediaOptions, type PasteDropMediaUploadFn, type PasteDropRehostProgressEvent, Popover, PopoverContent, PopoverTrigger, type RehostProgressEvent, SR_ONLY, Separator, Spacer, Toolbar, ToolbarGroup, ToolbarSeparator, UiState, UiState as UiStateType, type User, UserContext, type UserContextValue, UserProvider, Video, clamp, cn, defaultUiState, detectMediaKind, findNodeAtPosition, findNodePosition, findSelectionPosition, focusNextNode, formatShortcutKey, getAvatar, getElementOverflowPosition, getNodeDisplayName, getSelectedBlockNodes, getSelectedNodesOfType, getSelectionBoundingRect, getUrlParam, handleImageUpload, hasContentAbove, isAllowedUri, isExtensionAvailable, isMac, isMarkInSchema, isNodeInSchema, isNodeTypeSelected, isSelectionValid, isTextSelectionValid, isValidPosition, markHideFloatingOnNext, parseShortcutKeys, pickFile, removeEmptyParagraphs, resolveMaxSize, runMediaUpload, sanitizeUrl, selectCurrentBlockContent, selectNodeAndHideFloating, selectionWithinConvertibleTypes, updateNodesAttr, useCollab, useCollaboration, useComposedRef, useCursorVisibility, useEditorConfig, useElementRect, useFloatingElement, useFloatingToolbarVisibility, useIsBreakpoint, useIsomorphicLayoutEffect, useMenuNavigation, useOnClickOutside, useScrolling, useThrottledCallback, useTiptapEditor, useUiEditorState, useUiEditorState as useUiEditorStateDefault, useUnmount, useUser, useWindowSize };
+export { type ApiParamAttrs, ApiParamExtension, ArticleViewer, type ArticleViewerProps, Audio, ButtonProps, type CalloutAttrs, CalloutExtension, type CalloutType, CodeBlockExtension, CodeBlockOptions, CodeGroupExtension, CollabContext, type CollabContextValue, CollabProvider, type CollabProviderLike, Column, type ColumnLayout, Columns, ContentFormat, DEFAULT_MAX_FILE_SIZES, type DetailsAttrs, DetailsExtension, DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, type EditorCollabConfig, type EditorConfig, EditorConfigProvider, type EditorConfigProviderProps, EditorContentArea, type EditorProviderProps, type EditorUploadConfig, type EditorUserConfig, FileAttachment, type FileAttachmentAttrs, FloatingElement, HIDE_FLOATING_META, LoadingSpinner, MAC_SYMBOLS, MAX_FILE_SIZE, type MediaKind, type MediaKindForButton, MediaUploadButton, type MediaUploadButtonProps, MediaUploadPlaceholder, NotionEditor, NotionEditorContent, EditorProvider as NotionEditorInner, type NotionEditorProps, type OverflowPosition, type ParsedContent, PasteDropMedia, type PasteDropMediaOptions, type PasteDropMediaUploadFn, type PasteDropRehostProgressEvent, Popover, PopoverContent, PopoverTrigger, type RehostProgressEvent, type RenderHighlightedHTMLOptions, SR_ONLY, Separator, Spacer, Toolbar, ToolbarGroup, ToolbarSeparator, UiState, UiState as UiStateType, type User, UserContext, type UserContextValue, UserProvider, Video, clamp, cn, defaultUiState, detectMediaKind, findNodeAtPosition, findNodePosition, findSelectionPosition, focusNextNode, formatShortcutKey, getAvatar, getEditorMarkdown, getElementOverflowPosition, getNodeDisplayName, getSelectedBlockNodes, getSelectedNodesOfType, getSelectionBoundingRect, getUrlParam, handleImageUpload, hasContentAbove, isAllowedUri, isExtensionAvailable, isMac, isMarkInSchema, isNodeInSchema, isNodeTypeSelected, isSelectionValid, isTextSelectionValid, isValidPosition, markHideFloatingOnNext, parseEditorContent, parseShortcutKeys, pickFile, removeEmptyParagraphs, renderHighlightedHTML, resolveMaxSize, runMediaUpload, sanitizeUrl, selectCurrentBlockContent, selectNodeAndHideFloating, selectionWithinConvertibleTypes, serializeEditorMarkdown, updateNodesAttr, useCollab, useCollaboration, useComposedRef, useCursorVisibility, useEditorConfig, useElementRect, useFloatingElement, useFloatingToolbarVisibility, useIsBreakpoint, useIsomorphicLayoutEffect, useMenuNavigation, useOnClickOutside, useScrolling, useThrottledCallback, useTiptapEditor, useUiEditorState, useUiEditorState as useUiEditorStateDefault, useUnmount, useUser, useWindowSize };

package/dist/doc.js

@@ -1,5 +1,6 @@
-export { ArticleViewer, Audio, CollabContext, CollabProvider, Column, Columns, DEFAULT_MAX_FILE_SIZES, DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EditorConfigProvider, EditorContentArea, FileAttachment, FloatingElement, HIDE_FLOATING_META, LoadingSpinner, MediaUploadButton, MediaUploadPlaceholder, NotionEditor, NotionEditorContent, EditorProvider as NotionEditorInner, PasteDropMedia, Separator, Spacer, Toolbar, ToolbarGroup, ToolbarSeparator, UiState, UserContext, UserProvider, Video, defaultUiState, detectMediaKind, findSelectionPosition, hasContentAbove, markHideFloatingOnNext, pickFile, resolveMaxSize, runMediaUpload, selectNodeAndHideFloating, useCollab, useCollaboration, useComposedRef, useCursorVisibility, useEditorConfig, useElementRect, useFloatingElement, useFloatingToolbarVisibility, useIsBreakpoint, useIsomorphicLayoutEffect, useMenuNavigation, useOnClickOutside, useThrottledCallback, useUiEditorState, use_ui_editor_state_default as useUiEditorStateDefault, useUnmount, useUser, useWindowSize } from './chunk-IUDLMN53.js';
+export { ApiParamExtension, ArticleViewer, Audio, CalloutExtension, CodeBlockExtension, CodeGroupExtension, CollabContext, CollabProvider, Column, Columns, DEFAULT_MAX_FILE_SIZES, DetailsExtension, DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EditorConfigProvider, EditorContentArea, FileAttachment, FloatingElement, HIDE_FLOATING_META, LoadingSpinner, MediaUploadButton, MediaUploadPlaceholder, NotionEditor, NotionEditorContent, EditorProvider as NotionEditorInner, PasteDropMedia, Separator, Spacer, Toolbar, ToolbarGroup, ToolbarSeparator, UiState, UserContext, UserProvider, Video, defaultUiState, detectMediaKind, findSelectionPosition, getEditorMarkdown, hasContentAbove, markHideFloatingOnNext, parseEditorContent, pickFile, renderHighlightedHTML, resolveMaxSize, runMediaUpload, selectNodeAndHideFloating, serializeEditorMarkdown, useCollab, useCollaboration, useComposedRef, useCursorVisibility, useEditorConfig, useElementRect, useFloatingElement, useFloatingToolbarVisibility, useIsBreakpoint, useIsomorphicLayoutEffect, useMenuNavigation, useOnClickOutside, useThrottledCallback, useUiEditorState, use_ui_editor_state_default as useUiEditorStateDefault, useUnmount, useUser, useWindowSize } from './chunk-SGLNT6Z2.js';
 export { Button, MAC_SYMBOLS, MAX_FILE_SIZE, Popover, PopoverContent, PopoverTrigger, SR_ONLY, clamp, cn, findNodeAtPosition, findNodePosition, focusNextNode, formatShortcutKey, getAvatar, getElementOverflowPosition, getNodeDisplayName, getSelectedBlockNodes, getSelectedNodesOfType, getSelectionBoundingRect, getUrlParam, handleImageUpload, isAllowedUri, isExtensionAvailable, isMac, isMarkInSchema, isNodeInSchema, isNodeTypeSelected, isSelectionValid, isTextSelectionValid, isValidPosition, parseShortcutKeys, removeEmptyParagraphs, sanitizeUrl, selectCurrentBlockContent, selectionWithinConvertibleTypes, updateNodesAttr, useTiptapEditor } from './chunk-QMYT5WXO.js';
+import './chunk-ZY5KLA7T.js';
 import { useState, useEffect } from 'react';
 
 function useScrolling(target, options = {}) {

package/dist/doc.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/hooks/use-scrolling.ts"],"names":[],"mappings":";;;;AAWO,SAAS,YAAA,CACd,MAAA,EACA,OAAA,GAA+B,EAAC,EACvB;AACT,EAAA,MAAM,EAAE,QAAA,GAAW,GAAA,EAAK,kBAAA,GAAqB,MAAK,GAAI,OAAA;AACtD,EAAA,MAAM,CAAC,WAAA,EAAa,cAAc,CAAA,GAAI,SAAS,KAAK,CAAA;AAEpD,EAAA,SAAA,CAAU,MAAM;AAEd,IAAA,MAAM,OAAA,GACJ,UAAU,OAAO,MAAA,KAAW,eAAe,MAAA,YAAkB,MAAA,GACzD,MAAA,GACE,MAAA,EAAmC,OAAA,IAAW,MAAA;AAGtD,IAAA,MAAM,cACJ,kBAAA,IACA,OAAA,KAAY,UACZ,OAAO,QAAA,KAAa,cAChB,QAAA,GACA,OAAA;AAEN,IAAA,MAAM,EAAA,GAAK,CACT,EAAA,EACA,KAAA,EACA,YACG,EAAA,CAAG,gBAAA,CAAiB,KAAA,EAAO,OAAA,EAAS,IAAI,CAAA;AAE7C,IAAA,MAAM,GAAA,GAAM,CACV,EAAA,EACA,KAAA,EACA,YACG,EAAA,CAAG,mBAAA,CAAoB,OAAO,OAAO,CAAA;AAE1C,IAAA,IAAI,OAAA;AACJ,IAAA,MAAM,iBAAA,GAAoB,OAAA,KAAY,MAAA,IAAU,aAAA,IAAiB,MAAA;AAEjE,IAAA,MAAM,eAA8B,MAAM;AACxC,MAAA,IAAI,CAAC,WAAA,EAAa,cAAA,CAAe,IAAI,CAAA;AAErC,MAAA,IAAI,CAAC,iBAAA,EAAmB;AACtB,QAAA,YAAA,CAAa,OAAO,CAAA;AACpB,QAAA,OAAA,GAAU,UAAA,CAAW,MAAM,cAAA,CAAe,KAAK,GAAG,QAAQ,CAAA;AAAA,MAC5D;AAAA,IACF,CAAA;AAEA,IAAA,MAAM,eAAA,GAAiC,MAAM,cAAA,CAAe,KAAK,CAAA;AAEjE,IAAA,EAAA,CAAG,WAAA,EAAa,UAAU,YAAY,CAAA;AACtC,IAAA,IAAI,iBAAA,EAAmB;AACrB,MAAA,EAAA,CAAG,WAAA,EAAa,aAAa,eAAe,CAAA;AAAA,IAC9C;AAEA,IAAA,OAAO,MAAM;AACX,MAAA,GAAA,CAAI,WAAA,EAAa,UAAU,YAAY,CAAA;AACvC,MAAA,IAAI,iBAAA,EAAmB;AACrB,QAAA,GAAA,CAAI,WAAA,EAAa,aAAa,eAAe,CAAA;AAAA,MAC/C;AACA,MAAA,YAAA,CAAa,OAAO,CAAA;AAAA,IACtB,CAAA;AAAA,EACF,GAAG,CAAC,MAAA,EAAQ,QAAA,EAAU,kBAAA,EAAoB,WAAW,CAAC,CAAA;AAEtD,EAAA,OAAO,WAAA;AACT","file":"doc.js","sourcesContent":["import type { RefObject } from \"react\"\nimport { useEffect, useState } from \"react\"\n\ntype ScrollTarget = RefObject<HTMLElement> | Window | null | undefined\ntype EventTargetWithScroll = Window | HTMLElement | Document\n\ninterface UseScrollingOptions {\n  debounce?: number\n  fallbackToDocument?: boolean\n}\n\nexport function useScrolling(\n  target?: ScrollTarget,\n  options: UseScrollingOptions = {}\n): boolean {\n  const { debounce = 150, fallbackToDocument = true } = options\n  const [isScrolling, setIsScrolling] = useState(false)\n\n  useEffect(() => {\n    // Resolve element or window\n    const element: EventTargetWithScroll =\n      target && typeof Window !== \"undefined\" && target instanceof Window\n        ? target\n        : ((target as RefObject<HTMLElement>)?.current ?? window)\n\n    // Mobile: fallback to document when using window\n    const eventTarget: EventTargetWithScroll =\n      fallbackToDocument &&\n      element === window &&\n      typeof document !== \"undefined\"\n        ? document\n        : element\n\n    const on = (\n      el: EventTargetWithScroll,\n      event: string,\n      handler: EventListener\n    ) => el.addEventListener(event, handler, true)\n\n    const off = (\n      el: EventTargetWithScroll,\n      event: string,\n      handler: EventListener\n    ) => el.removeEventListener(event, handler)\n\n    let timeout: ReturnType<typeof setTimeout>\n    const supportsScrollEnd = element === window && \"onscrollend\" in window\n\n    const handleScroll: EventListener = () => {\n      if (!isScrolling) setIsScrolling(true)\n\n      if (!supportsScrollEnd) {\n        clearTimeout(timeout)\n        timeout = setTimeout(() => setIsScrolling(false), debounce)\n      }\n    }\n\n    const handleScrollEnd: EventListener = () => setIsScrolling(false)\n\n    on(eventTarget, \"scroll\", handleScroll)\n    if (supportsScrollEnd) {\n      on(eventTarget, \"scrollend\", handleScrollEnd)\n    }\n\n    return () => {\n      off(eventTarget, \"scroll\", handleScroll)\n      if (supportsScrollEnd) {\n        off(eventTarget, \"scrollend\", handleScrollEnd)\n      }\n      clearTimeout(timeout)\n    }\n  }, [target, debounce, fallbackToDocument, isScrolling])\n\n  return isScrolling\n}\n"]}
+{"version":3,"sources":["../src/hooks/use-scrolling.ts"],"names":[],"mappings":";;;;;AAWO,SAAS,YAAA,CACd,MAAA,EACA,OAAA,GAA+B,EAAC,EACvB;AACT,EAAA,MAAM,EAAE,QAAA,GAAW,GAAA,EAAK,kBAAA,GAAqB,MAAK,GAAI,OAAA;AACtD,EAAA,MAAM,CAAC,WAAA,EAAa,cAAc,CAAA,GAAI,SAAS,KAAK,CAAA;AAEpD,EAAA,SAAA,CAAU,MAAM;AAEd,IAAA,MAAM,OAAA,GACJ,UAAU,OAAO,MAAA,KAAW,eAAe,MAAA,YAAkB,MAAA,GACzD,MAAA,GACE,MAAA,EAAmC,OAAA,IAAW,MAAA;AAGtD,IAAA,MAAM,cACJ,kBAAA,IACA,OAAA,KAAY,UACZ,OAAO,QAAA,KAAa,cAChB,QAAA,GACA,OAAA;AAEN,IAAA,MAAM,EAAA,GAAK,CACT,EAAA,EACA,KAAA,EACA,YACG,EAAA,CAAG,gBAAA,CAAiB,KAAA,EAAO,OAAA,EAAS,IAAI,CAAA;AAE7C,IAAA,MAAM,GAAA,GAAM,CACV,EAAA,EACA,KAAA,EACA,YACG,EAAA,CAAG,mBAAA,CAAoB,OAAO,OAAO,CAAA;AAE1C,IAAA,IAAI,OAAA;AACJ,IAAA,MAAM,iBAAA,GAAoB,OAAA,KAAY,MAAA,IAAU,aAAA,IAAiB,MAAA;AAEjE,IAAA,MAAM,eAA8B,MAAM;AACxC,MAAA,IAAI,CAAC,WAAA,EAAa,cAAA,CAAe,IAAI,CAAA;AAErC,MAAA,IAAI,CAAC,iBAAA,EAAmB;AACtB,QAAA,YAAA,CAAa,OAAO,CAAA;AACpB,QAAA,OAAA,GAAU,UAAA,CAAW,MAAM,cAAA,CAAe,KAAK,GAAG,QAAQ,CAAA;AAAA,MAC5D;AAAA,IACF,CAAA;AAEA,IAAA,MAAM,eAAA,GAAiC,MAAM,cAAA,CAAe,KAAK,CAAA;AAEjE,IAAA,EAAA,CAAG,WAAA,EAAa,UAAU,YAAY,CAAA;AACtC,IAAA,IAAI,iBAAA,EAAmB;AACrB,MAAA,EAAA,CAAG,WAAA,EAAa,aAAa,eAAe,CAAA;AAAA,IAC9C;AAEA,IAAA,OAAO,MAAM;AACX,MAAA,GAAA,CAAI,WAAA,EAAa,UAAU,YAAY,CAAA;AACvC,MAAA,IAAI,iBAAA,EAAmB;AACrB,QAAA,GAAA,CAAI,WAAA,EAAa,aAAa,eAAe,CAAA;AAAA,MAC/C;AACA,MAAA,YAAA,CAAa,OAAO,CAAA;AAAA,IACtB,CAAA;AAAA,EACF,GAAG,CAAC,MAAA,EAAQ,QAAA,EAAU,kBAAA,EAAoB,WAAW,CAAC,CAAA;AAEtD,EAAA,OAAO,WAAA;AACT","file":"doc.js","sourcesContent":["import type { RefObject } from \"react\"\nimport { useEffect, useState } from \"react\"\n\ntype ScrollTarget = RefObject<HTMLElement> | Window | null | undefined\ntype EventTargetWithScroll = Window | HTMLElement | Document\n\ninterface UseScrollingOptions {\n  debounce?: number\n  fallbackToDocument?: boolean\n}\n\nexport function useScrolling(\n  target?: ScrollTarget,\n  options: UseScrollingOptions = {}\n): boolean {\n  const { debounce = 150, fallbackToDocument = true } = options\n  const [isScrolling, setIsScrolling] = useState(false)\n\n  useEffect(() => {\n    // Resolve element or window\n    const element: EventTargetWithScroll =\n      target && typeof Window !== \"undefined\" && target instanceof Window\n        ? target\n        : ((target as RefObject<HTMLElement>)?.current ?? window)\n\n    // Mobile: fallback to document when using window\n    const eventTarget: EventTargetWithScroll =\n      fallbackToDocument &&\n      element === window &&\n      typeof document !== \"undefined\"\n        ? document\n        : element\n\n    const on = (\n      el: EventTargetWithScroll,\n      event: string,\n      handler: EventListener\n    ) => el.addEventListener(event, handler, true)\n\n    const off = (\n      el: EventTargetWithScroll,\n      event: string,\n      handler: EventListener\n    ) => el.removeEventListener(event, handler)\n\n    let timeout: ReturnType<typeof setTimeout>\n    const supportsScrollEnd = element === window && \"onscrollend\" in window\n\n    const handleScroll: EventListener = () => {\n      if (!isScrolling) setIsScrolling(true)\n\n      if (!supportsScrollEnd) {\n        clearTimeout(timeout)\n        timeout = setTimeout(() => setIsScrolling(false), debounce)\n      }\n    }\n\n    const handleScrollEnd: EventListener = () => setIsScrolling(false)\n\n    on(eventTarget, \"scroll\", handleScroll)\n    if (supportsScrollEnd) {\n      on(eventTarget, \"scrollend\", handleScrollEnd)\n    }\n\n    return () => {\n      off(eventTarget, \"scroll\", handleScroll)\n      if (supportsScrollEnd) {\n        off(eventTarget, \"scrollend\", handleScrollEnd)\n      }\n      clearTimeout(timeout)\n    }\n  }, [target, debounce, fallbackToDocument, isScrolling])\n\n  return isScrolling\n}\n"]}

package/dist/docx.d.ts

@@ -104,6 +104,14 @@ interface ParseDocxResult {
     header: Record<string, unknown> | null;
     /** 默认页脚的结构化内容，同上 */
     footer: Record<string, unknown> | null;
+    /**
+     * 脚注。**键是正文上标标记 `[n]` 里的编号**（按引用出现顺序 1 起编），
+     * 宿主拿 `footnotes["1"]` 就是正文里 `[1]` 指的那条 —— 不用自己解 w:id。
+     * 编辑器没有脚注节点，所以注文不进文档树、导出 docx 时也不会写回。
+     */
+    footnotes: Record<string, Record<string, unknown>>;
+    /** 尾注，键的语义同 `footnotes`（编号序列与脚注各自独立） */
+    endnotes: Record<string, Record<string, unknown>>;
     /** 节属性原件，交给导出侧原样写回 */
     section: DocxSection;
 }
@@ -276,7 +284,14 @@ interface ImportDocxContext {
      * 但它只活在内存里：刷新页面 / 换设备就没了，要跨会话往返得自己存。
      */
     section: DocxSection;
+    /**
+     * 脚注。**键是正文上标标记 `[n]` 里的编号**（按引用出现顺序 1 起编）——
+     * 宿主拿 `footnotes["1"]` 就是正文 `[1]` 指的那条，不用自己解 w:id。
+     * 编辑器没有脚注节点：注文不进文档树，导出 docx 时也不会写回
+     * （导入时 warnings 里会明说）。
+     */
     footnotes: Record<string, JSONContent>;
+    /** 尾注，键的语义同 `footnotes`（编号序列与脚注各自独立） */
     endnotes: Record<string, JSONContent>;
 }
 interface ImportDocxCommandArgs {

package/dist/docx.js

@@ -1,8 +1,7 @@
+import { getCodeBlockTitle } from './chunk-ZY5KLA7T.js';
 import { Node, mergeAttributes, Extension } from '@tiptap/core';
 import { unzipSync, zipSync } from 'fflate';
 
-// src/docx/index.ts
-
 // src/docx/measure.ts
 function measureContentWidth(dom) {
   const el = dom;
@@ -142,9 +141,23 @@ function parseDocx(entries, opts) {
     paraSpacing: 0,
     paraIndent: 0,
     lists: 0,
-    listItems: 0
+    listItems: 0,
+    footnotes: 0,
+    endnotes: 0
   };
   const warnings = [];
+  const noteNumbers = {
+    footnote: /* @__PURE__ */ new Map(),
+    endnote: /* @__PURE__ */ new Map()
+  };
+  function noteNumber(kind, id) {
+    const seq = noteNumbers[kind];
+    const hit = seq.get(id);
+    if (hit !== void 0) return hit;
+    const n = seq.size + 1;
+    seq.set(id, n);
+    return n;
+  }
   const text = (p) => {
     const b = entries.read(p);
     return b ? decoder.decode(b) : null;
@@ -379,6 +392,17 @@ function parseDocx(entries, opts) {
         if (!n) continue;
         if (n.type === "image") out.blocks.push(n);
         else out.inline.push(n);
+      } else if (t === "w:footnoteReference" || t === "w:endnoteReference") {
+        const id = c.getAttribute("w:id");
+        if (!id) continue;
+        const kind = t === "w:footnoteReference" ? "footnote" : "endnote";
+        const n = noteNumber(kind, id);
+        const hasSuper = marks.some((m) => m.type === "superscript");
+        out.inline.push({
+          type: "text",
+          text: `[${n}]`,
+          marks: hasSuper ? marks : [...marks, { type: "superscript" }]
+        });
       } else if (t === "w:pict") {
         warnings.push("遇到 VML 图形（w:pict），未处理");
       }
@@ -706,6 +730,17 @@ function parseDocx(entries, opts) {
   if (!body) throw new Error("docx 缺少 w:body");
   const content = blocksOf(body);
   const doc = remapTypes({ type: "doc", content }, opts.prosemirrorNodes, opts.prosemirrorMarks);
+  const footnotes = notesOf("word/footnotes.xml", "w:footnote", "footnote");
+  const endnotes = notesOf("word/endnotes.xml", "w:endnote", "endnote");
+  if (recovered.footnotes || recovered.endnotes) {
+    const parts = [
+      ...recovered.footnotes ? [`${recovered.footnotes} 条脚注`] : [],
+      ...recovered.endnotes ? [`${recovered.endnotes} 条尾注`] : []
+    ];
+    warnings.push(
+      `文档有 ${parts.join("和")}：正文引用以上标 [n] 文本保留，注文在导入结果的 footnotes / endnotes 里（键即编号 n）。编辑器没有脚注节点，导出 docx 时不会写回`
+    );
+  }
   const section = readSection();
   const defaultHeader = section.refs.find((r) => r.kind === "header" && r.type === "default");
   const defaultFooter = section.refs.find((r) => r.kind === "footer" && r.type === "default");
@@ -716,8 +751,30 @@ function parseDocx(entries, opts) {
     ...opts.cssStyles ? { css: extractCss(stylesDoc) } : {},
     header: defaultHeader ? partContent(defaultHeader.path, "w:hdr") : null,
     footer: defaultFooter ? partContent(defaultFooter.path, "w:ftr") : null,
+    footnotes,
+    endnotes,
     section
   };
+  function notesOf(path, tag, kind) {
+    const d = xml(path);
+    if (!d) return {};
+    const out = {};
+    for (const el of Array.from(d.getElementsByTagName(tag))) {
+      const type = el.getAttribute("w:type");
+      if (type && type !== "normal") continue;
+      const id = el.getAttribute("w:id");
+      if (id === null) continue;
+      const blocks = blocksOf(el);
+      if (!blocks.length) continue;
+      out[String(noteNumber(kind, id))] = remapTypes(
+        { type: "doc", content: blocks },
+        opts.prosemirrorNodes,
+        opts.prosemirrorMarks
+      );
+      recovered[`${kind}s`] += 1;
+    }
+    return out;
+  }
   function partContent(path, root) {
     const d = xml(path);
     const el = d?.getElementsByTagName(root)[0];
@@ -1162,7 +1219,26 @@ function serializeDocx(doc, opts = {}) {
     });
     return `${xml}</w:tbl>`;
   }
-  function blocks(nodes) {
+  function codeBlock(n) {
+    return `<w:p><w:pPr><w:pStyle w:val="Code"/></w:pPr><w:r><w:rPr><w:rFonts w:ascii="Consolas" w:hAnsi="Consolas"/></w:rPr><w:t xml:space="preserve">${esc(collectText(n))}</w:t></w:r></w:p>`;
+  }
+  function indentPr(indent) {
+    return indent ? `<w:pPr><w:ind w:left="${indent}"/></w:pPr>` : "";
+  }
+  function boldParagraph(text, indent) {
+    return `<w:p>${indentPr(indent)}<w:r><w:rPr><w:b/></w:rPr><w:t xml:space="preserve">${esc(text)}</w:t></w:r></w:p>`;
+  }
+  function apiParamHeader(n, indent) {
+    const a = n.attrs ?? {};
+    const runs = [];
+    if (a.name) runs.push(`<w:r><w:rPr><w:b/></w:rPr><w:t xml:space="preserve">${esc(a.name)}</w:t></w:r>`);
+    if (a.type) runs.push(`<w:r><w:rPr><w:rFonts w:ascii="Consolas" w:hAnsi="Consolas"/></w:rPr><w:t xml:space="preserve"> ${esc(a.type)}</w:t></w:r>`);
+    if (a.required) runs.push(`<w:r><w:t xml:space="preserve"> 必选</w:t></w:r>`);
+    if (a.default != null) runs.push(`<w:r><w:t xml:space="preserve"> 默认值 ${esc(a.default)}</w:t></w:r>`);
+    if (a.summary) runs.push(`<w:r><w:t xml:space="preserve"> ｜ ${esc(a.summary)}</w:t></w:r>`);
+    return `<w:p>${indentPr(indent)}${runs.join("")}</w:p>`;
+  }
+  function blocks(nodes, indent = 0) {
     const out = [];
     for (const n of nodes) {
       switch (n.type) {
@@ -1170,7 +1246,7 @@ function serializeDocx(doc, opts = {}) {
           out.push(heading(n));
           break;
         case "paragraph":
-          out.push(paragraph(n));
+          out.push(paragraph(n, [], indent || void 0));
           break;
         case "bulletList":
         case "orderedList":
@@ -1183,7 +1259,32 @@ function serializeDocx(doc, opts = {}) {
           for (const c of n.content ?? []) out.push(paragraph(c, [], 720));
           break;
         case "codeBlock":
-          out.push(`<w:p><w:pPr><w:pStyle w:val="Code"/></w:pPr><w:r><w:rPr><w:rFonts w:ascii="Consolas" w:hAnsi="Consolas"/></w:rPr><w:t xml:space="preserve">${esc(collectText(n))}</w:t></w:r></w:p>`);
+          out.push(codeBlock(n));
+          break;
+        case "codeGroup":
+          for (const child of n.content ?? []) {
+            if (child.type !== "codeBlock") {
+              warnings.push(`codeGroup 里出现非代码块节点 "${child.type}"，已跳过`);
+              continue;
+            }
+            out.push(`<w:p><w:r><w:rPr><w:b/></w:rPr><w:t xml:space="preserve">${esc(codeLabel(child))}</w:t></w:r></w:p>`);
+            out.push(codeBlock(child));
+          }
+          break;
+        case "details":
+          out.push(boldParagraph(String(n.attrs?.title ?? "") || "详情", indent));
+          out.push(blocks(n.content ?? [], indent));
+          break;
+        case "callout": {
+          const type = String(n.attrs?.type ?? "info");
+          const title = String(n.attrs?.title ?? "") || calloutDefaultTitle(type);
+          out.push(boldParagraph(title, indent));
+          out.push(blocks(n.content ?? [], indent + 720));
+          break;
+        }
+        case "apiParam":
+          out.push(apiParamHeader(n, indent));
+          out.push(blocks(n.content ?? [], indent + 720));
           break;
         case "horizontalRule":
           out.push('<w:p><w:pPr><w:pBdr><w:bottom w:val="single" w:sz="6" w:color="auto"/></w:pBdr></w:pPr></w:p>');
@@ -1280,6 +1381,13 @@ function cssFontStack(v) {
   if (!parts.length) return null;
   return { ascii: parts[0], eastAsia: parts[parts.length - 1] };
 }
+function calloutDefaultTitle(type) {
+  return { info: "信息", tip: "提示", warning: "注意", danger: "危险" }[type] ?? "信息";
+}
+function codeLabel(n) {
+  const attrs = n.attrs ?? {};
+  return getCodeBlockTitle({ language: attrs.language ?? null, label: attrs.label ?? null });
+}
 function collectText(n) {
   if (n?.type === "text") return n.text ?? "";
   return (n?.content ?? []).map(collectText).join("");
@@ -1542,8 +1650,8 @@ var ImportDocx = Extension.create({
               header: result.header,
               footer: result.footer,
               section: result.section,
-              footnotes: {},
-              endnotes: {}
+              footnotes: result.footnotes,
+              endnotes: result.endnotes
             });
           } catch (e) {
             const err = e instanceof Error ? e : new Error(String(e));