@formulaxjs/ckeditor5 0.2.2 → 0.3.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.
Files changed (9) hide show
  1. package/README.md +14 -0
  2. package/README.zh-CN.md +247 -233
  3. package/dist/index.cjs +87 -71
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.global.js +36321 -35829
  6. package/dist/index.global.js.map +1 -1
  7. package/dist/index.js +82 -63
  8. package/dist/index.js.map +1 -1
  9. package/package.json +4 -3
package/README.md CHANGED
@@ -17,6 +17,8 @@ CKEditor 5 integration adapter for FormulaX.
17
17
  - Double-click editing for existing formulas
18
18
  - Persist only LaTeX source in the CKEditor 5 model
19
19
  - Runtime SVG rendering in the editing view
20
+ - Default read-only rendering through `@formulaxjs/renderer-kity`
21
+ - Optional runtime preload before the first modal open
20
22
  - Upcast and downcast support for formula markup in editor data
21
23
  - Direct modal helper export through `openFormulaXModal`
22
24
 
@@ -61,6 +63,7 @@ import {
61
63
  import 'ckeditor5/ckeditor5.css';
62
64
 
63
65
  import { FormulaX } from '@formulaxjs/ckeditor5';
66
+ import { createKityFormulaRenderer } from '@formulaxjs/renderer-kity';
64
67
 
65
68
  await ClassicEditor.create(document.querySelector('#editor')!, {
66
69
  licenseKey: 'GPL',
@@ -76,6 +79,9 @@ await ClassicEditor.create(document.querySelector('#editor')!, {
76
79
  modal: {
77
80
  title: 'FormulaX Editor',
78
81
  },
82
+ renderer: createKityFormulaRenderer({
83
+ fontSize: 40,
84
+ }),
79
85
  editor: {
80
86
  render: {
81
87
  fontsize: 40,
@@ -161,6 +167,10 @@ When editor data is downcast to HTML, generated formula nodes are marked with `d
161
167
 
162
168
  The editing view renders formula SVG at runtime from the persisted LaTeX. The exact rendered inner HTML is internal and may evolve. Consumers should rely on the plugin and exported options rather than hard-coding the full markup shape.
163
169
 
170
+ ## Custom renderer
171
+
172
+ The adapter accepts a `renderer` option. By default it uses `createKityFormulaRenderer()` from `@formulaxjs/renderer-kity`.
173
+
164
174
  ## Options
165
175
 
166
176
  ```ts
@@ -172,6 +182,8 @@ interface FormulaXCKEditor5Options {
172
182
  cursorStyle?: string;
173
183
  formulaClassName?: string;
174
184
  formulaAttributeName?: string;
185
+ renderer?: FormulaRenderer;
186
+ preload?: FormulaXEditorPreloadMode;
175
187
  modal?: {
176
188
  title?: string;
177
189
  insertText?: string;
@@ -199,6 +211,8 @@ interface FormulaXCKEditor5Options {
199
211
  | `cursorStyle` | `pointer` | Cursor style applied to generated formula nodes. |
200
212
  | `formulaClassName` | `formulax-math` | CSS class used by generated formula nodes. |
201
213
  | `formulaAttributeName` | `data-formulax-latex` | Attribute used to persist source LaTeX. |
214
+ | `renderer` | `createKityFormulaRenderer()` | Renderer used for runtime SVG output in the editing view. |
215
+ | `preload` | `idle` | Preloads the FormulaX runtime on browser idle, on host hover/focus, or never. |
202
216
  | `modal` | see below | Modal labels and closing behavior. |
203
217
  | `editor` | see below | Embedded FormulaX editor options. |
204
218
 
package/README.zh-CN.md CHANGED
@@ -1,169 +1,179 @@
1
- # @formulaxjs/ckeditor5
2
-
3
- [English](./README.md) | 简体中文
4
-
5
- FormulaX 的 CKEditor 5 集成适配器。
6
-
1
+ # @formulaxjs/ckeditor5
2
+
3
+ [English](./README.md) | 简体中文
4
+
5
+ FormulaX 的 CKEditor 5 集成适配器。
6
+
7
7
  `@formulaxjs/ckeditor5` 提供了一个 CKEditor 5 插件，会以弹窗形式打开 FormulaX 编辑器，用于在 CKEditor 5 内容中插入和更新行内公式。
8
-
9
- > 状态：实验阶段。在首个稳定版本发布前，公共 API 仍可能调整。
10
-
11
- ## 功能特性
12
-
13
- - 通过 `FormulaX` 导出 CKEditor 5 插件
14
- - 基于 CKEditor 5 `componentFactory` 注册工具栏按钮
15
- - 通过 `editor.execute('formulaX')` 在代码中主动打开
16
- - 将公式作为行内 widget object 插入和更新
8
+
9
+ > 状态：实验阶段。在首个稳定版本发布前，公共 API 仍可能调整。
10
+
11
+ ## 功能特性
12
+
13
+ - 通过 `FormulaX` 导出 CKEditor 5 插件
14
+ - 基于 CKEditor 5 `componentFactory` 注册工具栏按钮
15
+ - 通过 `editor.execute('formulaX')` 在代码中主动打开
16
+ - 将公式作为行内 widget object 插入和更新
17
17
  - 支持双击编辑已有公式
18
18
  - 在 CKEditor 5 model 中仅持久化 LaTeX 源内容
19
19
  - 在 editing view 中运行时渲染 SVG
20
+ - 默认通过 `@formulaxjs/renderer-kity` 完成只读渲染
21
+ - 支持在首次打开弹窗前预加载 runtime
20
22
  - 支持在编辑器数据中对公式 markup 进行 upcast 和 downcast
21
23
  - 直接导出弹窗工具函数 `openFormulaXModal`
22
-
23
- ## 兼容性
24
-
25
- 该包将 CKEditor 5 声明为可选 peer dependency：
26
-
27
- ```json
28
- {
29
- "ckeditor5": ">=42 <49"
30
- }
31
- ```
32
-
33
- 当前工作空间中的 demo 使用的是 CKEditor 5 `46.1.1`。
34
-
35
- ## 安装
36
-
37
- 包发布后可使用：
38
-
39
- ```bash
40
- pnpm add @formulaxjs/ckeditor5
41
- pnpm add ckeditor5
42
- ```
43
-
44
- 在 FormulaX 工作空间内，直接使用 workspace 包：
45
-
46
- ```bash
47
- pnpm install
48
- pnpm dev:ckeditor5
49
- ```
50
-
51
- ## 基础使用
52
-
53
- 将 `FormulaX` 加入 CKEditor 5 的插件列表，并配置对应的工具栏项：
54
-
55
- ```ts
56
- import {
57
- ClassicEditor,
58
- Essentials,
59
- Paragraph,
60
- } from 'ckeditor5';
24
+
25
+ ## 兼容性
26
+
27
+ 该包将 CKEditor 5 声明为可选 peer dependency：
28
+
29
+ ```json
30
+ {
31
+ "ckeditor5": ">=42 <49"
32
+ }
33
+ ```
34
+
35
+ 当前工作空间中的 demo 使用的是 CKEditor 5 `46.1.1`。
36
+
37
+ ## 安装
38
+
39
+ 包发布后可使用：
40
+
41
+ ```bash
42
+ pnpm add @formulaxjs/ckeditor5
43
+ pnpm add ckeditor5
44
+ ```
45
+
46
+ 在 FormulaX 工作空间内，直接使用 workspace 包：
47
+
48
+ ```bash
49
+ pnpm install
50
+ pnpm dev:ckeditor5
51
+ ```
52
+
53
+ ## 基础使用
54
+
55
+ 将 `FormulaX` 加入 CKEditor 5 的插件列表，并配置对应的工具栏项：
56
+
57
+ ```ts
58
+ import {
59
+ ClassicEditor,
60
+ Essentials,
61
+ Paragraph,
62
+ } from 'ckeditor5';
61
63
  import 'ckeditor5/ckeditor5.css';
62
64
 
63
65
  import { FormulaX } from '@formulaxjs/ckeditor5';
64
-
65
- await ClassicEditor.create(document.querySelector('#editor')!, {
66
- licenseKey: 'GPL',
67
- plugins: [
68
- Essentials,
69
- Paragraph,
70
- FormulaX,
71
- ],
72
- toolbar: ['formulaX'],
66
+ import { createKityFormulaRenderer } from '@formulaxjs/renderer-kity';
67
+
68
+ await ClassicEditor.create(document.querySelector('#editor')!, {
69
+ licenseKey: 'GPL',
70
+ plugins: [
71
+ Essentials,
72
+ Paragraph,
73
+ FormulaX,
74
+ ],
75
+ toolbar: ['formulaX'],
73
76
  formulaX: {
74
77
  toolbarText: 'FormulaX',
75
78
  tooltip: '插入或编辑公式',
76
79
  modal: {
77
80
  title: 'FormulaX 公式编辑器',
78
81
  },
82
+ renderer: createKityFormulaRenderer({
83
+ fontSize: 40,
84
+ }),
79
85
  editor: {
80
86
  render: {
81
87
  fontsize: 40,
82
- },
83
- },
84
- },
85
- } as any);
86
- ```
87
-
88
- 之后用户可以点击 `FormulaX` 工具栏按钮插入公式。已有公式可以通过双击更新，也可以先选中后再次执行同一个命令进行更新。
89
-
90
- ## 自定义 model 名称
91
-
92
- 默认的 CKEditor 5 model 名称是 `formulaX`。
93
-
94
- 如果宿主编辑器里已经存在同名 model，可以在 `formulaX` 配置里传入自定义 `name`：
95
-
96
- ```ts
97
- await ClassicEditor.create(document.querySelector('#editor')!, {
98
- plugins: [Essentials, Paragraph, FormulaX],
99
- toolbar: ['formulaX'],
100
- formulaX: {
101
- name: 'inlineMath',
102
- },
103
- } as any);
104
- ```
105
-
106
- 如果 CKEditor 5 检测到配置的 model 名称已经被注册，插件会输出一条 `console.error`，并跳过本次注册，避免悄悄创建冲突的 schema 定义。
107
-
108
- ## 代码中主动打开
109
-
110
- 插件注册的命令名与 `buttonName` 保持一致。默认配置下可直接调用：
111
-
112
- ```ts
113
- editor.execute('formulaX');
114
- ```
115
-
116
- ## 自定义按钮名称
117
-
118
- 默认的工具栏按钮名和命令名都是 `formulaX`。
119
-
120
- 如果自定义它，需要确保 CKEditor 5 的 `toolbar` 配置与自定义名称保持一致：
121
-
122
- ```ts
123
- await ClassicEditor.create(document.querySelector('#editor')!, {
124
- plugins: [Essentials, Paragraph, FormulaX],
125
- toolbar: ['myFormulaX'],
126
- formulaX: {
127
- buttonName: 'myFormulaX',
128
- toolbarText: 'FormulaX',
129
- },
130
- } as any);
131
- ```
132
-
133
- 代码中主动打开时，也要使用同一个自定义命令名：
134
-
135
- ```ts
136
- editor.execute('myFormulaX');
137
- ```
138
-
139
- ## 持久化数据与 markup
140
-
141
- CKEditor 5 的 model 层只保存公式的 LaTeX 源内容：
142
-
143
- ```ts
144
- <formulaX latex="\\sqrt{x}" />
145
- ```
146
-
147
- 当编辑器数据 downcast 为 HTML 时，生成的公式节点默认会通过 `data-formulax="true"` 标记，并将 LaTeX 源内容保存在 `data-formulax-latex` 中：
148
-
149
- ```html
150
- <span
151
- class="formulax-math"
152
- data-formulax="true"
153
- data-formulax-latex="\\sqrt{x}"
154
- data-latex="\\sqrt{x}"
155
- contenteditable="false"
156
- role="button"
157
- style="cursor: pointer"
158
- tabindex="0"
159
- ></span>
160
- ```
161
-
88
+ },
89
+ },
90
+ },
91
+ } as any);
92
+ ```
93
+
94
+ 之后用户可以点击 `FormulaX` 工具栏按钮插入公式。已有公式可以通过双击更新，也可以先选中后再次执行同一个命令进行更新。
95
+
96
+ ## 自定义 model 名称
97
+
98
+ 默认的 CKEditor 5 model 名称是 `formulaX`。
99
+
100
+ 如果宿主编辑器里已经存在同名 model，可以在 `formulaX` 配置里传入自定义 `name`：
101
+
102
+ ```ts
103
+ await ClassicEditor.create(document.querySelector('#editor')!, {
104
+ plugins: [Essentials, Paragraph, FormulaX],
105
+ toolbar: ['formulaX'],
106
+ formulaX: {
107
+ name: 'inlineMath',
108
+ },
109
+ } as any);
110
+ ```
111
+
112
+ 如果 CKEditor 5 检测到配置的 model 名称已经被注册，插件会输出一条 `console.error`，并跳过本次注册，避免悄悄创建冲突的 schema 定义。
113
+
114
+ ## 代码中主动打开
115
+
116
+ 插件注册的命令名与 `buttonName` 保持一致。默认配置下可直接调用：
117
+
118
+ ```ts
119
+ editor.execute('formulaX');
120
+ ```
121
+
122
+ ## 自定义按钮名称
123
+
124
+ 默认的工具栏按钮名和命令名都是 `formulaX`。
125
+
126
+ 如果自定义它，需要确保 CKEditor 5 的 `toolbar` 配置与自定义名称保持一致：
127
+
128
+ ```ts
129
+ await ClassicEditor.create(document.querySelector('#editor')!, {
130
+ plugins: [Essentials, Paragraph, FormulaX],
131
+ toolbar: ['myFormulaX'],
132
+ formulaX: {
133
+ buttonName: 'myFormulaX',
134
+ toolbarText: 'FormulaX',
135
+ },
136
+ } as any);
137
+ ```
138
+
139
+ 代码中主动打开时，也要使用同一个自定义命令名：
140
+
141
+ ```ts
142
+ editor.execute('myFormulaX');
143
+ ```
144
+
145
+ ## 持久化数据与 markup
146
+
147
+ CKEditor 5 的 model 层只保存公式的 LaTeX 源内容：
148
+
149
+ ```ts
150
+ <formulaX latex="\\sqrt{x}" />
151
+ ```
152
+
153
+ 当编辑器数据 downcast 为 HTML 时，生成的公式节点默认会通过 `data-formulax="true"` 标记，并将 LaTeX 源内容保存在 `data-formulax-latex` 中：
154
+
155
+ ```html
156
+ <span
157
+ class="formulax-math"
158
+ data-formulax="true"
159
+ data-formulax-latex="\\sqrt{x}"
160
+ data-latex="\\sqrt{x}"
161
+ contenteditable="false"
162
+ role="button"
163
+ style="cursor: pointer"
164
+ tabindex="0"
165
+ ></span>
166
+ ```
167
+
162
168
  编辑态中的 SVG 由持久化的 LaTeX 在运行时生成。用于渲染公式的内部 HTML 结构属于实现细节，后续可能演进。业务侧应优先依赖插件能力和导出的配置项，而不是写死完整 markup 结构。
163
169
 
164
- ## 配置项
170
+ ## 自定义 renderer
165
171
 
166
- ```ts
172
+ 该适配器支持 `renderer` 配置项。默认值是来自 `@formulaxjs/renderer-kity` 的 `createKityFormulaRenderer()`。
173
+
174
+ ## 配置项
175
+
176
+ ```ts
167
177
  interface FormulaXCKEditor5Options {
168
178
  name?: string;
169
179
  buttonName?: string;
@@ -172,99 +182,103 @@ interface FormulaXCKEditor5Options {
172
182
  cursorStyle?: string;
173
183
  formulaClassName?: string;
174
184
  formulaAttributeName?: string;
185
+ renderer?: FormulaRenderer;
186
+ preload?: FormulaXEditorPreloadMode;
175
187
  modal?: {
176
188
  title?: string;
177
189
  insertText?: string;
178
- updateText?: string;
179
- cancelText?: string;
180
- closeOnBackdrop?: boolean;
181
- };
182
- editor?: {
183
- height?: number | string;
184
- autofocus?: boolean;
185
- assets?: Partial<KityEditorAssets>;
186
- render?: {
187
- fontsize?: number;
188
- };
189
- };
190
- }
191
- ```
192
-
193
- | 配置项 | 默认值 | 说明 |
194
- | --- | --- | --- |
195
- | `name` | `formulaX` | 用于持久化公式节点的 CKEditor 5 model/schema 元素名。 |
196
- | `buttonName` | `formulaX` | CKEditor 5 的工具栏按钮名，同时也是命令名。 |
197
- | `toolbarText` | `FormulaX` | 工具栏按钮显示文本。 |
198
- | `tooltip` | `Insert or edit formula` | 工具栏按钮 tooltip。 |
190
+ updateText?: string;
191
+ cancelText?: string;
192
+ closeOnBackdrop?: boolean;
193
+ };
194
+ editor?: {
195
+ height?: number | string;
196
+ autofocus?: boolean;
197
+ assets?: Partial<KityEditorAssets>;
198
+ render?: {
199
+ fontsize?: number;
200
+ };
201
+ };
202
+ }
203
+ ```
204
+
205
+ | 配置项 | 默认值 | 说明 |
206
+ | --- | --- | --- |
207
+ | `name` | `formulaX` | 用于持久化公式节点的 CKEditor 5 model/schema 元素名。 |
208
+ | `buttonName` | `formulaX` | CKEditor 5 的工具栏按钮名，同时也是命令名。 |
209
+ | `toolbarText` | `FormulaX` | 工具栏按钮显示文本。 |
210
+ | `tooltip` | `Insert or edit formula` | 工具栏按钮 tooltip。 |
199
211
  | `cursorStyle` | `pointer` | 应用于生成公式节点的鼠标光标样式。 |
200
212
  | `formulaClassName` | `formulax-math` | 生成的公式节点 CSS class。 |
201
213
  | `formulaAttributeName` | `data-formulax-latex` | 用于保存 LaTeX 源内容的属性。 |
214
+ | `renderer` | `createKityFormulaRenderer()` | editing view 中运行时 SVG 输出使用的 renderer。 |
215
+ | `preload` | `idle` | 控制在浏览器空闲时、宿主 hover/focus 时，或完全不预加载 FormulaX runtime。 |
202
216
  | `modal` | 见下方 | 弹窗文案和关闭行为。 |
203
217
  | `editor` | 见下方 | 内嵌 FormulaX 编辑器配置。 |
204
-
205
- ### Modal 配置
206
-
207
- | 配置项 | 默认值 | 说明 |
208
- | --- | --- | --- |
209
- | `title` | `FormulaX Editor` | 弹窗标题。 |
210
- | `insertText` | `Insert` | 插入公式时的提交按钮文本。 |
211
- | `updateText` | `Update` | 更新公式时的提交按钮文本。 |
212
- | `cancelText` | `Cancel` | 取消按钮文本。 |
213
- | `closeOnBackdrop` | `true` | 点击遮罩层时是否关闭弹窗。 |
214
-
215
- ### Editor 配置
216
-
217
- | 配置项 | 默认值 | 说明 |
218
- | --- | --- | --- |
219
- | `height` | `100%` | 内嵌编辑器高度。 |
220
- | `autofocus` | `true` | 内嵌编辑器是否自动聚焦。 |
221
- | `assets` | `{}` | 可选的 Kity runtime 资源覆盖配置。 |
222
- | `render.fontsize` | `40` | 公式渲染字号。 |
223
-
224
- ## 导出 API
225
-
226
- | 导出 | 说明 |
227
- | --- | --- |
228
- | `FormulaX` | CKEditor 5 插件类。 |
229
- | `default` | 与 `FormulaX` 相同。 |
230
- | `FormulaXCommand` | 插件内部使用的命令实现。 |
231
- | `resolveOptions` | 将用户配置与默认配置合并为完整配置。 |
232
- | `openFormulaXModal` | 直接打开 FormulaX 弹窗。 |
233
- | `DEFAULT_MODEL_NAME` | 默认的 CKEditor 5 model 名称。 |
234
- | `DEFAULT_BUTTON_NAME` | 默认的 CKEditor 5 命令名和工具栏按钮名。 |
235
- | `DEFAULT_FORMULA_ATTRIBUTE` | 默认的 LaTeX 持久化属性名。 |
236
- | `DEFAULT_FORMULA_CLASS` | 默认的公式节点 CSS class。 |
237
- | `FORMULA_FLAG_ATTRIBUTE` | 用于在编辑器数据中识别 FormulaX 节点的属性。 |
238
-
239
- ## 开发
240
-
241
- 在仓库根目录执行：
242
-
243
- ```bash
244
- pnpm install
245
- pnpm dev:ckeditor5
246
- ```
247
-
248
- 仅构建该包：
249
-
250
- ```bash
251
- pnpm --filter @formulaxjs/ckeditor5 build
252
- ```
253
-
254
- 运行该包类型检查：
255
-
256
- ```bash
257
- pnpm --filter @formulaxjs/ckeditor5 typecheck
258
- ```
259
-
260
- ## Demo
261
-
262
- 本地 demo：
263
-
264
- ```bash
265
- pnpm dev:ckeditor5
266
- ```
267
-
268
- GitHub Pages demo：
269
-
270
- [https://vndmea.github.io/formulaX/ckeditor5/](https://vndmea.github.io/formulaX/ckeditor5/)
218
+
219
+ ### Modal 配置
220
+
221
+ | 配置项 | 默认值 | 说明 |
222
+ | --- | --- | --- |
223
+ | `title` | `FormulaX Editor` | 弹窗标题。 |
224
+ | `insertText` | `Insert` | 插入公式时的提交按钮文本。 |
225
+ | `updateText` | `Update` | 更新公式时的提交按钮文本。 |
226
+ | `cancelText` | `Cancel` | 取消按钮文本。 |
227
+ | `closeOnBackdrop` | `true` | 点击遮罩层时是否关闭弹窗。 |
228
+
229
+ ### Editor 配置
230
+
231
+ | 配置项 | 默认值 | 说明 |
232
+ | --- | --- | --- |
233
+ | `height` | `100%` | 内嵌编辑器高度。 |
234
+ | `autofocus` | `true` | 内嵌编辑器是否自动聚焦。 |
235
+ | `assets` | `{}` | 可选的 Kity runtime 资源覆盖配置。 |
236
+ | `render.fontsize` | `40` | 公式渲染字号。 |
237
+
238
+ ## 导出 API
239
+
240
+ | 导出 | 说明 |
241
+ | --- | --- |
242
+ | `FormulaX` | CKEditor 5 插件类。 |
243
+ | `default` | 与 `FormulaX` 相同。 |
244
+ | `FormulaXCommand` | 插件内部使用的命令实现。 |
245
+ | `resolveOptions` | 将用户配置与默认配置合并为完整配置。 |
246
+ | `openFormulaXModal` | 直接打开 FormulaX 弹窗。 |
247
+ | `DEFAULT_MODEL_NAME` | 默认的 CKEditor 5 model 名称。 |
248
+ | `DEFAULT_BUTTON_NAME` | 默认的 CKEditor 5 命令名和工具栏按钮名。 |
249
+ | `DEFAULT_FORMULA_ATTRIBUTE` | 默认的 LaTeX 持久化属性名。 |
250
+ | `DEFAULT_FORMULA_CLASS` | 默认的公式节点 CSS class。 |
251
+ | `FORMULA_FLAG_ATTRIBUTE` | 用于在编辑器数据中识别 FormulaX 节点的属性。 |
252
+
253
+ ## 开发
254
+
255
+ 在仓库根目录执行：
256
+
257
+ ```bash
258
+ pnpm install
259
+ pnpm dev:ckeditor5
260
+ ```
261
+
262
+ 仅构建该包：
263
+
264
+ ```bash
265
+ pnpm --filter @formulaxjs/ckeditor5 build
266
+ ```
267
+
268
+ 运行该包类型检查：
269
+
270
+ ```bash
271
+ pnpm --filter @formulaxjs/ckeditor5 typecheck
272
+ ```
273
+
274
+ ## Demo
275
+
276
+ 本地 demo：
277
+
278
+ ```bash
279
+ pnpm dev:ckeditor5
280
+ ```
281
+
282
+ GitHub Pages demo：
283
+
284
+ [https://vndmea.github.io/formulaX/ckeditor5/](https://vndmea.github.io/formulaX/ckeditor5/)