@yanglingfeng/md-web 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ylfeng250
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# @yanglingfeng/md-web
+
+接近马克飞象书写体验的 React Markdown 编辑器组件：左边专注写作，右边即时呈现。支持 GFM、公式、流程图、时序图、文内目录、脚注，以及图片粘贴上传。
+
+![编辑器分屏界面：左侧 Earthsong 源码，右侧实时预览](./image.png)
+
+## 安装
+
+```bash
+npm install @yanglingfeng/md-web
+```
+
+需要 React 18 或以上。样式会随组件入口自动引入；如果宿主打包器没有处理 CSS，再手动加一行：
+
+```ts
+import '@yanglingfeng/md-web/style.css'
+```
+
+## 使用
+
+```tsx
+import { useState } from 'react'
+import { MarkdownEditor } from '@yanglingfeng/md-web'
+
+export function EditorPage() {
+  const [value, setValue] = useState('# 新文档')
+
+  return (
+    <MarkdownEditor
+      value={value}
+      onChange={setValue}
+      height="100vh"
+      onImageUpload={async (file, signal) => {
+        const body = new FormData()
+        body.append('file', file)
+        const response = await fetch('/api/images', {
+          method: 'POST',
+          body,
+          signal,
+        })
+        const result = await response.json()
+        return { url: result.url, alt: file.name }
+      }}
+    />
+  )
+}
+```
+
+本地存储、上传接口都由宿主实现。组件本身不会写 `localStorage`。
+
+### 常用属性
+
+| 属性 | 说明 |
+| --- | --- |
+| `value` / `defaultValue` / `onChange` | 受控或非受控文档内容 |
+| `mode` / `onModeChange` | `split`、`edit`、`preview` |
+| `theme` | `earthsong`（默认）或 `light` |
+| `height` | 数字像素或 CSS 高度，默认 `100vh` |
+| `onImageUpload` | 粘贴 / 拖放图片时由宿主上传并返回 URL |
+| `onError` | 图表渲染失败、上传失败等错误回调 |
+| `renderStatus` | 自定义底栏：行号、列号、字数、字符数 |
+| `shortcuts` | 覆盖加粗、链接、图片、预览、最大化、帮助等快捷键 |
+| `readOnly` | 只读，禁用工具栏写入与快捷键改写 |
+
+也单独导出 `MarkdownPreview`、`runEditorCommand` 以及相关类型。
+
+## 功能
+
+- CodeMirror 6 编辑内核：撤销重做、行号、自动换行、列表续行、Tab 缩进
+- 工具栏与快捷键：加粗、标题、链接、图片、公式、表格等，支持再次点击取消格式
+- 三种视图：分屏、最大化编辑器、纯预览；分栏可拖拽
+- 预览语法：GFM 任务与表格、KaTeX 公式、代码高亮、`[TOC]`、脚注、`@(笔记本)[标签]`
+- 图表：` ```mermaid `、` ```flow `（flowchart.js）、` ```sequence `（js-sequence-diagrams），默认按自然尺寸展示，可点击放大
+- 目录与同步滚动：右侧迷你工具条打开文档目录，分屏时编辑区与预览双向对齐
+- 安全渲染：禁用原始 HTML、链接协议白名单；图表在无脚本权限的 iframe 沙箱中绘制
+
+## 预览语法
+
+除了常见 Markdown 与 GFM，还支持马克飞象风格的扩展写法：
+
+````md
+@(示例笔记本)[写作|帮助]
+
+[TOC]
+
+正文里可以加脚注[^1]。
+
+```flow
+st=>start: Start
+e=>end
+st->e
+```
+
+```sequence
+Alice->Bob: Hello
+```
+
+[^1]: 脚注说明。
+````
+
+流程图与时序图会先改写成等价的 Mermaid，再在沙箱 iframe 中渲染。图表默认缩小展示，悬停后可放大查看。
+
+## 本地开发
+
+```bash
+npm install
+npm run dev
+```
+
+质量检查与构建：
+
+```bash
+npm run typecheck
+npm run lint
+npm test
+npm run build        # 打包 npm 库到 dist/
+npm run build:demo   # 打包演示站到 dist-demo/
+```
+
+演示页会把草稿防抖写入 `localStorage`，这只存在于本仓库的 App，不会打进 npm 包。
+
+## 发布
+
+```bash
+npm login
+npm publish
+```
+
+`prepublishOnly` 会先跑类型检查、测试和库构建。

package/dist/MarkdownEditor.d.ts

@@ -0,0 +1,2 @@
+import { MarkdownEditorProps } from './types';
+export declare function MarkdownEditor({ value, defaultValue, onChange, mode: modeProp, onModeChange, readOnly, height, theme, className, ariaLabel, shortcuts, onImageUpload, onError, renderStatus, }: MarkdownEditorProps): import("react").JSX.Element;

package/dist/MarkdownPreview.d.ts

@@ -0,0 +1,6 @@
+interface MarkdownPreviewProps {
+    source: string;
+    onError?: (error: Error) => void;
+}
+export declare function MarkdownPreview({ source, onError }: MarkdownPreviewProps): import("react").JSX.Element;
+export {};

package/dist/Toolbar.d.ts

@@ -0,0 +1,10 @@
+import { EditorCommand, EditorMode } from './types';
+interface ToolbarProps {
+    mode: EditorMode;
+    readOnly: boolean;
+    onCommand: (command: EditorCommand) => void;
+    onModeChange: (mode: EditorMode) => void;
+    onDownload: () => void;
+}
+export declare function Toolbar({ mode, readOnly, onCommand, onModeChange, onDownload, }: ToolbarProps): import("react").JSX.Element;
+export {};

package/dist/editorCommands.d.ts

@@ -0,0 +1,10 @@
+import { EditorView } from '@codemirror/view';
+import { EditorCommand } from './types';
+interface Transformation {
+    text: string;
+    selectionFrom: number;
+    selectionTo: number;
+}
+export declare function transformSelection(command: EditorCommand, selectedText: string): Transformation;
+export declare function runEditorCommand(view: EditorView | null, command: EditorCommand): boolean;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { MarkdownEditor } from './MarkdownEditor';
+export { MarkdownPreview } from './MarkdownPreview';
+export { runEditorCommand, transformSelection } from './editorCommands';
+export type { EditorCommand, EditorMode, EditorTheme, ImageUploadResult, MarkdownEditorProps, MarkdownEditorShortcuts, TocItem, } from './types';