@one2x/medeo-rte 0.4.1 → 0.4.2

package/README.md

@@ -54,30 +54,28 @@ new Editor(el, { plugins: [...builtinEmbedPlugins, formulaPlugin] });
 
 文字与段落样式、列表、表格、链接、图文绕排、Markdown 边打边转、撤销重做、中文 IME。
 
-嵌入对象走同一套插件接口：图片、视频、代码块、公式、同步块引用、以及下面三类「槽 / 胶囊」。**名字都带 slot，用途完全不同，不要混用。**
+嵌入对象走同一套插件接口：图片、视频、代码块、公式、同步块引用，以及两种芯片。**名字都带 slot，用途完全不同，不要混用。** 模板里可点、可生成、按字折行的那截文字用 **`mark`**，不是芯片。
 
-### 三类 slot 对照（接入必读）
+### 两种芯片对照（接入必读）
 
-| | `internalSlot` | `hostSlot` | `virtualSlot`（+ `region`） |
-| --- | --- | --- | --- |
-| 是什么 | SDK 内置芯片（`slotPlugin`） | 宿主自绘芯片 | 虚拟块文本槽；外层皮是 `region` |
-| 落在哪 | `EmbedEntity`，流上一个 `*` | 同上 | `virtualBlocks` 区间，**不占**额外字符 |
-| 内容 | 实体字段（label / slotValue 等） | `hostType` + `data`，DOM 由宿主画 | 就是那段 `spacers` 文字 |
-| 折行 | 整颗盒子，放不下换行 | 同左 | 槽里的字跟外层句子一起按字折 |
-| 谁用 | demo / 简单内置控件 | **产品业务胶囊**（下拉、`@`、上传等） | **模板里可填灰字**、外层底色分组 |
-| 插入 | `commands.insertSlot('text'\|'image'\|'select')` | `commands.insertHostEmbed(...)` 或 `insertSlice` 的 `entities` | `insertSlice` 的 `virtualBlocks`，或 `insertVirtualBlock` |
+| | `internalSlot` | `hostSlot` |
+| --- | --- | --- |
+| 是什么 | SDK 内置芯片（`slotPlugin`） | 宿主自绘芯片 |
+| 落在哪 | `EmbedEntity`，流上一个 `*` | 同上 |
+| 内容 | 实体字段（label / slotValue 等） | `hostType` + `data`，DOM 由宿主画 |
+| 折行 | 整颗盒子，放不下换行 | 同左 |
+| 谁用 | demo / 简单内置控件 | **产品业务胶囊**（下拉、`@`、上传等） |
+| 插入 | `commands.insertSlot('text'\|'image'\|'select')` | `commands.insertHostEmbed(...)` 或 `insertSlice` 的 `entities` |
 
-另外还有 **同步块**（fragment / ref）：选区提成可复用内容，改一处全变——和上面三类无关。
-
-产品模板句里「可填写的那截灰字」用 **`virtualSlot`**，不要用 `internalSlot` / `hostSlot`。后两者是另一颗盒子，点进去才填，不能按字切开。
+另外还有 **同步块**（fragment / ref）：选区提成可复用内容，改一处全变。芯片整颗换行；要按字折行、点击出菜单、展示生成中，用下面的 `mark`。
 
 ## 虚拟块怎么用（业务侧）
 
 虚拟块是盖在字符流上的假块：负责皮（背景、圆角）和「整段选中」交互。区间里的字仍是文档正文。用户打字**不会**新建虚拟块，只能由业务 API 插入。
 
-三种 kind：
+两种 kind：
 
-- **`mark`**：纯样式叠层（高亮底色、边框、文字缺省色等）。**交互与普通文本流完全一致**：点击落光标、方向键逐字走、能选中、能编辑；不进选中/进出状态机，不参与嵌套（`parentId` 恒为 `null`），可与其他块任意叠放。右边缘继续输入算区间内（背景跟着延伸），遇到换行就断；区间内文字删光后自动移除。样式只需配 `chrome.background`、`chrome.radius`（圆角，默认 3；折行时只有首行的上两角和末行的下两角是圆角，其余角为直角，单行自然四角全圆）、`chrome.paddingX`（水平内边距）和 `chrome.hoverBackground`（鼠标悬停时整段含折行各行换成这个底色）：
+- **`mark`**：纯样式叠层（高亮底色、边框、文字缺省色等）。点击落在字上，块内方向键逐字走。从外侧朝块内按方向键不会走进去，而是先把整段文字选中（就是一段普通选区，焦点留在来的这一侧）；再按一次方向键跳到另一侧外侧。整段选中时 Shift+方向键按普通选区缩小或扩大。上下键从块外落到块内时同样先选中整段。同一条边上有多块重叠时选范围最大的那块；两块紧挨着时，跳过前一块的同一次按键会选中下一块。不参与嵌套（`parentId` 恒为 `null`），可与其他块任意叠放。光标停在左右边界时都分内外两侧：从块内走到边界或点在底色里是**内侧**，输入算区间内（背景跟着延伸，遇到换行就断）；在边界上再朝块外按一次方向键，或点在底色外，是**外侧**（光标画在底色外），输入的文字留在块外、同一行。其他方式落到边界（`setSelection`、撤销等）时，右边界默认内侧、左边界默认外侧。没有 `placeholder` 时，区间内文字删光后块自动移除；有 `placeholder` 时收成零宽，灰字由 SDK 画出来，不进正文，方向键也不把它当成整段选中。样式只需配 `chrome.background`、`chrome.radius`（圆角，默认 3；折行时只有首行的上两角和末行的下两角是圆角，其余角为直角，单行自然四角全圆）、`chrome.paddingX`（水平内边距，不传按 4px，传 `0` 表示不留）、`chrome.hoverBackground`（鼠标悬停时整段含折行各行换成这个底色）和 `chrome.placeholderColor`（灰字颜色，不传是 `#98a2b3`）：
 
   ```ts
   editor.insertVirtualBlock({
@@ -86,67 +84,77 @@ new Editor(el, { plugins: [...builtinEmbedPlugins, formulaPlugin] });
   });
   ```
 
-  `paddingX` 只外扩底色/边框，**不参与排版**（字形位置、折行、行高都不变），行首/行尾也会外扩，所以相邻文字和相邻 mark 的底色可能互相重叠；行首行尾的外扩部分画在内容区外：SDK 默认让画布和 `.mini-page-wrap` 左右各多出 5px（负 margin 抵消，文字位置不变），所以 `paddingX` 在 5px 以内开箱即用，更大就要靠编辑器 `padding.x` 补足。**宿主若覆盖 `.mini-page-wrap` 的 `padding`，请保留 `padding-inline: 5px; margin-inline: -5px;`，否则文字会左移 5px、外扩被裁**。不支持垂直内边距。
-- **`region`**：一层皮 / 分组。整段选中时打字、删除会被忽略（保住模板壳）。没有 `editing` 模式。
-- **`virtualSlot`**：最内层文本槽。可进 `editing`；空着时显示 `placeholder`，填了就是用户字；整段删回 placeholder，槽本身留下。
+  `paddingX` 和 CSS 行内元素的 padding 一样**占排版宽度**：mark 真正的起点前、终点后各让出 `paddingX`，前后文字和相邻 mark 不会压在底色上，光标在内外侧的位置也正好是下一个字落下的位置。折行处不让位，底色在行首/行尾外扩，外扩部分画在内容区外：SDK 默认让画布和 `.mini-page-wrap` 左右各多出 5px（负 margin 抵消，文字位置不变），所以 `paddingX` 在 5px 以内开箱即用，更大就要靠编辑器 `padding.x` 补足。**宿主若覆盖 `.mini-page-wrap` 的 `padding`，请保留 `padding-inline: 5px; margin-inline: -5px;`，否则文字会左移 5px、外扩被裁**。不支持垂直内边距。
+
+  **空态。** `placeholder` 不是正文，复制、保存、`getContent()` 里都没有这段字。删光或 `replaceMarkText(id, '')` 后块留在原下标，两种光标亲和打字都会写进块里。没传 `placeholder` 的 mark 不能建成零宽，删光即拆掉。
+
+  ```ts
+  const id = editor.insertVirtualBlock({
+    kind: 'mark',
+    placeholder: 'Describe a scene',
+    chrome: { background: '#fff3bf', placeholderColor: '#98a2b3' }
+  });
+  // 光标在这块里（含空块、内侧边界）时：
+  editor.on('markenter', ({ id }) => {});
+  editor.on('markleave', ({ id }) => {});
+  // 点击这块。锁定中不发，但光标仍会落下。
+  editor.on('markclick', ({ id }) => openMenu(id));
+  ```
+
+  **中间态（生成中）。** `setMarkStatus` 只活在编辑器里，不进文档、撤销栈、复制和 `getContent()`。`label` 盖住正文；比正文宽时这一行临时撑开，清掉状态后宽度恢复。`locked: true` 时，块内和内侧边界上的输入、删除、粘贴、回车不生效，点击也不发 `markclick`；外侧打字仍然落在块外。生成结束后先清状态，再用 `replaceMarkText` 把结果写回去，这一步单独占一次撤销。
 
-嵌套规则（针对 `region` / `virtualSlot`）：只允许包含、不允许交叉；`virtualSlot` 必须是叶子。`mark` 不受此限。日常编辑里业务**不用维护** `[start, end)`，插删字时 SDK 自动挪区间。
+  ```ts
+  editor.setMarkStatus(id, { label: 'Generating…', locked: true, text: 'rainbow', border: 'pulse' });
+  editor.setMarkStatus(id, null);
+  editor.replaceMarkText(id, 'a red bicycle');
+  ```
+
+  `text: 'rainbow'` 只作用于 `label`。`border: 'pulse'` 是底色边缘的呼吸描边。HTML 用 CSS 动画，canvas 由 SDK 逐帧重画。块被拆掉或 `setContent` 换文档后，状态自动丢掉。
+
+  点击后的菜单位置用 `getVirtualBlockRect(id)`，返回的是屏幕坐标，不用再向 SDK 要点击点。
+
+`mark` 是目前唯一的虚拟块。`parentId` 恒为 `null`，多块可以重叠。日常编辑里业务**不用维护** `[start, end)`，插删字时 SDK 自动挪区间。
 
 ### 路径 A：整段模板一次插入（推荐）
 
-文案 + 槽 + 胶囊一起走 `insertSlice`。`virtualBlocks` 里的下标是**相对这段 `text`** 的半开区间：
+文案 + mark + 胶囊一起走 `insertSlice`。`virtualBlocks` 里的下标是**相对这段 `text`** 的半开区间：
 
 ```ts
 editor.insertSlice({
-  text: 'Write a prompt for Input a theme.\n',
+  text: 'Write a prompt for a red bicycle.\n',
   styles: [],
   entities: [],
   virtualBlocks: [
     {
-      id: 'region',
+      id: 'phrase',
       parentId: null,
-      kind: 'region',
-      start: 0,
-      end: 33,
-      chrome: { background: 'rgba(43,108,255,0.08)', radius: 8 }
-    },
-    {
-      id: 'slot',
-      parentId: 'region',
-      kind: 'virtualSlot',
+      kind: 'mark',
       start: 19,
-      end: 32,
-      placeholder: 'Input a theme',
-      empty: true,
-      chrome: { background: 'rgba(16,185,129,0.18)', placeholderColor: '#98a2b3' }
+      end: 33,
+      placeholder: 'a red bicycle',
+      chrome: { background: '#fff3bf', placeholderColor: '#98a2b3' }
     }
   ]
 });
 ```
 
-完整样例见 `demo/vblocks.ts`。
+可点击生成的样例见 `demo/vblocks.ts` 和 demo 右下角「插入可生成 mark」。
 
 ### 路径 B：给已有字套皮
 
 ```ts
 // 不传 start/end → 用当前选区
 editor.insertVirtualBlock({
-  kind: 'region',
-  chrome: { background: 'rgba(43,108,255,0.08)', radius: 8 }
-});
-
-editor.insertVirtualBlock({
-  kind: 'virtualSlot',
-  placeholder: 'Input a theme',
-  empty: true,
-  chrome: { background: 'rgba(16,185,129,0.18)', placeholderColor: '#98a2b3' }
+  kind: 'mark',
+  placeholder: 'Describe a scene',
+  chrome: { background: '#fff3bf', placeholderColor: '#98a2b3' }
 });
 
 // 也可显式下标
-editor.insertVirtualBlock({ kind: 'region', start: 0, end: 20, chrome: { ... } });
+editor.insertVirtualBlock({ kind: 'mark', start: 0, end: 20, chrome: { background: '#fff3bf' } });
 ```
 
-可配的 `chrome` 字段：`background`、`hoverBackground`（仅 mark）、`radius`、`borderColor` / `borderWidth`、`paddingX`（仅水平）、文字缺省（`color`、`fontSize`、`fontFamily`、`fontWeight`、`bold`、`italic`）、`placeholderColor`（仅 virtualSlot）。
+可配的 `chrome` 字段：`background`、`hoverBackground`（仅 mark）、`radius`、`borderColor` / `borderWidth`、`paddingX`（仅水平）、文字缺省（`color`、`fontSize`、`fontFamily`、`fontWeight`、`bold`、`italic`）、`placeholderColor`（mark 的灰字）。
 
 改皮 / 拆皮：`updateVirtualBlock(id, chrome)`、`removeVirtualBlock(id)`（只拆皮，字和胶囊留下）。
 
@@ -154,14 +162,14 @@ editor.insertVirtualBlock({ kind: 'region', start: 0, end: 20, chrome: { ... } }
 
 SDK 不画业务菜单。宿主自己：
 
-1. 听 `statechange`，看 `getState().vblockStack` 栈顶是否是某槽的 `editing`（点击或键盘进入都会触发）
-2. `editor.getVirtualBlockRect(id)` 拿屏幕坐标（clientX/Y，含滚动）定位浮层：`left/top/width/height` 是外接矩形，折行的块还有 `lines`；下拉放在 `left` / `top + height` 即可。滚动或重排后（`layoutchange`）重新取
-3. 写入：槽正处于 `editing` 时直接 `editor.insertText(text)`——空槽会整段覆盖 placeholder，不会进段落
-4. 关闭浮层：栈顶不再是该槽，或点到编辑器外（宿主自己监听）
+1. 听 `markclick`，参数是 `{ id }`。锁定中的 mark 不发这个事件
+2. `editor.getVirtualBlockRect(id)` 拿屏幕坐标（clientX/Y，含滚动）定位浮层：`left/top/width/height` 是外接矩形，折行的块还有 `lines`；下拉放在 `left` / `top + height` 即可。滚动或重排后（`layoutchange`）重新取。不需要点击点坐标
+3. 生成中：`setMarkStatus(id, { label, locked: true, text: 'rainbow', border: 'pulse' })`
+4. 写回：`setMarkStatus(id, null)` 然后 `replaceMarkText(id, text)`，这一步单独占一次撤销
 
 ### 和 host 胶囊一起用
 
-胶囊是流上的 `*`，可以落在 region 覆盖范围内，但**不是**虚拟块的子节点。自定义芯片：
+胶囊是流上的 `*`，可以落在 mark 覆盖范围内，但**不是**虚拟块的子节点。自定义芯片：
 
 ```ts
 const editor = new Editor(el, {
@@ -175,7 +183,7 @@ const editor = new Editor(el, {
 editor.commands.insertHostEmbed('Upscale', { label: '@Upscale' }, { width: 88, height: 24 });
 ```
 
-更细的模型与选区栈见 [virtual-blocks.md](./docs/virtual-blocks.md)。
+更细的模型见 [virtual-blocks.md](./docs/virtual-blocks.md)。
 
 ### API 一览
 
@@ -183,11 +191,13 @@ editor.commands.insertHostEmbed('Upscale', { label: '@Upscale' }, { width: 88, h
 | --- | --- |
 | `new Editor(el, options?)` | `doc` / `paint` / `plugins` / `hostEmbed` / `width` / `padding` / `placeholder` / `textDefaults` / `shortcuts` / `autofocus` / `chrome` |
 | `commands` | 公开编辑命令（加粗、插表、插图、`insertHostEmbed`、同步块等），宿主工具栏调这些 |
-| `on(event, fn)` | `change` / `selectionchange` / `statechange` / `layoutchange`，返回退订函数 |
-| `getState()` | 当前状态快照（含 `vblockStack`），用于同步 UI |
+| `on(event, fn)` | `change` / `selectionchange` / `statechange` / `layoutchange` 无参数；`markclick` / `markenter` / `markleave` 收到 `{ id }`。返回退订函数 |
+| `getState()` | 当前状态快照，用于同步 UI |
 | `getContent()` / `setContent()` | 整篇内容读写，`Slice` 结构（含 `virtualBlocks`） |
 | `insertSlice(slice, at?)` | 插入切片；模板混排走这条 |
-| `insertVirtualBlock` / `updateVirtualBlock` / `removeVirtualBlock` | 套皮、改 chrome、拆皮 |
+| `insertVirtualBlock` / `updateVirtualBlock` / `removeVirtualBlock` | 套皮、改 chrome、拆皮。mark 带 `placeholder` 时 `start === end` 可以，用来放一块空灰字 |
+| `setMarkStatus(id, status \| null)` | mark 的中间态：`label` / `locked` / `text: 'rainbow'` / `border: 'pulse'`。不进文档和撤销 |
+| `replaceMarkText(id, text)` | 换掉 mark 里的字，块和 id 留下，整步一次撤销。空串按有没有 placeholder 收成灰字或拆块 |
 | `insertHostEmbed(hostType, data?, size?, at?)` | 插入宿主自绘胶囊 |
 | `getSelection()` / `setSelection()` | 选区读写 |
 | `getLayout()` | 排版几何（只读），做标尺、小地图、槽上浮层用 |