@formulaxjs/tinymce 0.1.0

package/LICENSE

@@ -0,0 +1,35 @@
+# MIT License
+
+Copyright (c) 2024 FormulaX Contributors
+
+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.
+
+---
+
+## Legacy KityFormula Code
+
+Portions of FormulaX, specifically within the `@formulaxjs/kity-runtime` package,
+contain code adapted from [KityFormula](https://github.com/BaiduFE/kityformula)
+by Baidu FEX Team, originally released under the MIT License.
+
+KityFormula-related code in FormulaX is retained under the same MIT License
+and is subject to the copyright notice above.
+
+For details on the original KityFormula project, see:
+https://github.com/BaiduFE/kityformula

package/README.md

@@ -0,0 +1,277 @@
+# @formulaxjs/tinymce
+
+English | [简体中文](./README.zh-CN.md)
+
+TinyMCE integration adapter for FormulaX.
+
+`@formulaxjs/tinymce` registers FormulaX as a TinyMCE plugin and provides a modal-based formula editing experience for inserting and updating formulas inside TinyMCE content.
+
+> Status: experimental. Public APIs may change before the first stable release.
+
+## Features
+
+- TinyMCE plugin registration through `registerFormulaXTinyMcePlugin`
+- FormulaX toolbar button and menu item support
+- `FormulaXOpen` TinyMCE command for programmatic opening
+- Insert and update formulas as non-editable inline nodes
+- Double-click, Enter, and Space editing interactions for existing formulas
+- TinyMCE compatibility layer for versions `>=5 <9`
+- LaTeX persistence through `data-formulax-latex`
+- Markup helpers for creating, parsing, serializing, finding, and replacing formula elements
+
+## Compatibility
+
+The package declares TinyMCE as an optional peer dependency:
+
+```json
+{
+  "tinymce": ">=5 <9"
+}
+```
+
+The adapter is designed for TinyMCE 5, 6, 7, and 8. Unsupported major versions will emit a console warning.
+
+The workspace demo can dynamically load TinyMCE 5, 6, 7, or 8 from CDN for compatibility verification.
+
+## Install
+
+When the package is published:
+
+```bash
+pnpm add @formulaxjs/tinymce
+pnpm add tinymce
+```
+
+Inside the FormulaX workspace, use the workspace package directly:
+
+```bash
+pnpm install
+pnpm dev:tinymce
+```
+
+## Basic usage
+
+Register the FormulaX TinyMCE plugin before calling `tinymce.init`:
+
+```ts
+import tinymce from 'tinymce';
+import { registerFormulaXTinyMcePlugin } from '@formulaxjs/tinymce';
+
+registerFormulaXTinyMcePlugin(tinymce, {
+  toolbarText: 'FormulaX',
+  tooltip: 'Insert or edit formula',
+  modal: {
+    title: 'FormulaX Editor',
+  },
+  editor: {
+    mode: 'kity',
+    height: '100%',
+    autofocus: true,
+    render: { fontsize: 40 },
+  },
+});
+
+await tinymce.init({
+  selector: '#editor',
+  height: 420,
+  menubar: false,
+  plugins: 'formulax',
+  toolbar: 'undo redo | formulax',
+  license_key: 'gpl',
+});
+```
+
+Then users can click the `FormulaX` toolbar button to insert a formula. Existing formulas can be edited by double-clicking them or selecting them and pressing Enter or Space.
+
+## Programmatic opening
+
+The plugin registers the `FormulaXOpen` command:
+
+```ts
+editor.execCommand('FormulaXOpen');
+```
+
+## Custom plugin names
+
+The default plugin, button, and menu item names are all `formulax`.
+
+If you customize them, keep the TinyMCE `plugins` and `toolbar` configuration aligned with the custom names:
+
+```ts
+registerFormulaXTinyMcePlugin(tinymce, {
+  pluginName: 'formulaXPlugin',
+  buttonName: 'formulaXButton',
+  menuItemName: 'formulaXMenuItem',
+});
+
+await tinymce.init({
+  selector: '#editor',
+  plugins: 'formulaXPlugin',
+  toolbar: 'formulaXButton',
+});
+```
+
+## Formula markup helpers
+
+Use markup helpers when you need to generate or inspect FormulaX formula nodes outside the plugin UI:
+
+```ts
+import {
+  createTinyMceFormulaMarkup,
+  getFormulaLatexFromElement,
+  isFormulaElement,
+  replaceFormulaElement,
+} from '@formulaxjs/tinymce';
+
+const html = createTinyMceFormulaMarkup('\\sqrt{x}');
+
+const element = document.querySelector('[data-formulax="true"]');
+if (isFormulaElement(element)) {
+  const latex = getFormulaLatexFromElement(element);
+  replaceFormulaElement(element, `${latex}+1`);
+}
+```
+
+A generated formula node stores the source LaTeX in `data-formulax-latex` and is marked with `data-formulax="true"`:
+
+```html
+<span
+  class="formulax-math"
+  data-formulax="true"
+  data-formulax-latex="\\sqrt{x}"
+  data-latex="\\sqrt{x}"
+  contenteditable="false"
+  data-mce-contenteditable="false"
+  style="cursor: pointer"
+></span>
+```
+
+The exact generated markup is internal and may evolve. Consumers should rely on the exported helper functions where possible.
+
+## Options
+
+```ts
+interface FormulaXTinyMceOptions {
+  pluginName?: string;
+  buttonName?: string;
+  menuItemName?: string;
+  toolbarText?: string;
+  tooltip?: string;
+  cursorStyle?: string;
+  formulaClassName?: string;
+  formulaAttributeName?: string;
+  renderMode?: 'text' | 'html';
+  initialLatex?: string;
+  modal?: FormulaXModalOptions;
+  editor?: FormulaXEditorOptions;
+}
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `pluginName` | `formulax` | TinyMCE plugin name registered through `tinymce.PluginManager.add`. |
+| `buttonName` | `formulax` | Toolbar button name. |
+| `menuItemName` | `formulax` | Menu item name. |
+| `toolbarText` | `FormulaX` | Toolbar and menu item label. |
+| `tooltip` | `Insert formula` | Toolbar button tooltip. |
+| `cursorStyle` | `pointer` | Cursor style applied to generated formula nodes. |
+| `formulaClassName` | `formulax-math` | CSS class used by generated formula nodes. |
+| `formulaAttributeName` | `data-formulax-latex` | Attribute used to persist source LaTeX. |
+| `renderMode` | `text` | Experimental render mode option. |
+| `initialLatex` | empty string | Initial LaTeX when inserting a new formula. |
+| `modal` | see below | Modal labels, dimensions, and closing behavior. |
+| `editor` | see below | Embedded FormulaX editor options. |
+
+### Modal options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `title` | `FormulaX` | Modal title. |
+| `insertText` | `Insert` | Submit button text when inserting. |
+| `updateText` | `Update` | Submit button text when updating. |
+| `cancelText` | `Cancel` | Cancel button text. |
+| `width` | `1100px` | Modal width. |
+| `height` | `auto` | Modal height. |
+| `closeOnBackdrop` | `true` | Whether clicking the backdrop closes the modal. |
+
+### Editor options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `mode` | `kity` | Formula editor runtime mode. |
+| `height` | `100%` | Embedded editor height. |
+| `autofocus` | `true` | Whether the embedded editor should autofocus. |
+| `assets` | `{}` | Optional Kity runtime asset overrides. |
+| `render.fontsize` | `40` | Formula render font size. |
+
+## Exported API
+
+| Export | Description |
+| --- | --- |
+| `registerFormulaXTinyMcePlugin` | Registers the TinyMCE plugin. |
+| `resolveOptions` | Resolves user options into required defaults. |
+| `openFormulaXOverlayModal` | Opens the FormulaX modal directly. |
+| `createTinyMceFormulaMarkup` | Creates formula HTML from LaTeX. |
+| `parseTinyMceFormulaMarkup` | Parses LaTeX into a FormulaX document. |
+| `serializeTinyMceFormulaMarkup` | Serializes a FormulaX document into TinyMCE formula HTML. |
+| `getFormulaLatexFromElement` | Reads source LaTeX from a formula element. |
+| `findFormulaElement` | Finds the nearest FormulaX formula element. |
+| `isFormulaElement` | Checks whether a node is a FormulaX formula element. |
+| `replaceFormulaElement` | Replaces an existing formula element with updated markup. |
+| `getTinyMceMajorVersion` | Reads the TinyMCE major version. |
+| `createTinyMceCompat` | Creates the internal TinyMCE compatibility facade. |
+| `warnUnsupportedTinyMceVersion` | Emits a warning for unsupported TinyMCE versions. |
+
+## Development
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm dev:tinymce
+```
+
+Build only this package:
+
+```bash
+pnpm --filter @formulaxjs/tinymce build
+```
+
+Run package tests:
+
+```bash
+pnpm --filter @formulaxjs/tinymce test
+```
+
+Run package type checking:
+
+```bash
+pnpm --filter @formulaxjs/tinymce typecheck
+```
+
+## Demo
+
+Local demo:
+
+```bash
+pnpm dev:tinymce
+```
+
+GitHub Pages demo:
+
+[https://vndmea.github.io/formulaX/tinymce/](https://vndmea.github.io/formulaX/tinymce/)
+
+The demo includes a TinyMCE version selector and is intended to stay close to the standalone FormulaX playground experience.
+
+## Notes and limitations
+
+- TinyMCE versions below 5 and 9 or newer are not officially supported.
+- The API is still experimental.
+- If your host TinyMCE configuration performs strict content filtering, ensure FormulaX formula spans and SVG output are allowed.
+- The current editing UI uses the FormulaX Kity-compatible runtime.
+
+## License
+
+FormulaX license information should be reviewed before public npm publishing.
+
+KityFormula-related code and assets retain their original copyright and license notices.

package/README.zh-CN.md

@@ -0,0 +1,277 @@
+# @formulaxjs/tinymce
+
+[English](./README.md) | 简体中文
+
+FormulaX 的 TinyMCE 集成适配器。
+
+`@formulaxjs/tinymce` 会将 FormulaX 注册为 TinyMCE 插件，并提供基于弹窗的公式编辑体验，用于在 TinyMCE 内容中插入和更新公式。
+
+> 状态：实验阶段。在首个稳定版本发布前，公共 API 仍可能调整。
+
+## 功能特性
+
+- 通过 `registerFormulaXTinyMcePlugin` 注册 TinyMCE 插件
+- 支持 FormulaX 工具栏按钮和菜单项
+- 提供 `FormulaXOpen` TinyMCE 命令，便于代码中主动打开公式编辑器
+- 将公式作为不可直接编辑的 inline 节点插入和更新
+- 支持双击、Enter、Space 编辑已有公式
+- 面向 TinyMCE `>=5 <9` 的兼容层
+- 通过 `data-formulax-latex` 持久化 LaTeX 源内容
+- 提供创建、解析、序列化、查找和替换公式元素的 markup 工具函数
+
+## 兼容性
+
+该包将 TinyMCE 声明为可选 peer dependency：
+
+```json
+{
+  "tinymce": ">=5 <9"
+}
+```
+
+适配器设计目标为 TinyMCE 5、6、7、8。对于不支持的主版本，会输出 console warning。
+
+工作空间中的 demo 可以通过 CDN 动态加载 TinyMCE 5、6、7、8，用于兼容性验证。
+
+## 安装
+
+包发布后可使用：
+
+```bash
+pnpm add @formulaxjs/tinymce
+pnpm add tinymce
+```
+
+在 FormulaX 工作空间内，直接使用 workspace 包：
+
+```bash
+pnpm install
+pnpm dev:tinymce
+```
+
+## 基础使用
+
+在调用 `tinymce.init` 之前注册 FormulaX TinyMCE 插件：
+
+```ts
+import tinymce from 'tinymce';
+import { registerFormulaXTinyMcePlugin } from '@formulaxjs/tinymce';
+
+registerFormulaXTinyMcePlugin(tinymce, {
+  toolbarText: 'FormulaX',
+  tooltip: '插入或编辑公式',
+  modal: {
+    title: 'FormulaX 公式编辑器',
+  },
+  editor: {
+    mode: 'kity',
+    height: '100%',
+    autofocus: true,
+    render: { fontsize: 40 },
+  },
+});
+
+await tinymce.init({
+  selector: '#editor',
+  height: 420,
+  menubar: false,
+  plugins: 'formulax',
+  toolbar: 'undo redo | formulax',
+  license_key: 'gpl',
+});
+```
+
+之后用户可以点击 `FormulaX` 工具栏按钮插入公式。已有公式可以通过双击编辑，也可以选中后按 Enter 或 Space 编辑。
+
+## 代码中主动打开
+
+插件会注册 `FormulaXOpen` 命令：
+
+```ts
+editor.execCommand('FormulaXOpen');
+```
+
+## 自定义插件名称
+
+默认情况下，插件名、按钮名、菜单项名均为 `formulax`。
+
+如果自定义这些名称，需要确保 TinyMCE 的 `plugins` 和 `toolbar` 配置与自定义名称保持一致：
+
+```ts
+registerFormulaXTinyMcePlugin(tinymce, {
+  pluginName: 'formulaXPlugin',
+  buttonName: 'formulaXButton',
+  menuItemName: 'formulaXMenuItem',
+});
+
+await tinymce.init({
+  selector: '#editor',
+  plugins: 'formulaXPlugin',
+  toolbar: 'formulaXButton',
+});
+```
+
+## 公式 markup 工具函数
+
+当需要在插件 UI 之外生成或检查 FormulaX 公式节点时，可以使用 markup 工具函数：
+
+```ts
+import {
+  createTinyMceFormulaMarkup,
+  getFormulaLatexFromElement,
+  isFormulaElement,
+  replaceFormulaElement,
+} from '@formulaxjs/tinymce';
+
+const html = createTinyMceFormulaMarkup('\\sqrt{x}');
+
+const element = document.querySelector('[data-formulax="true"]');
+if (isFormulaElement(element)) {
+  const latex = getFormulaLatexFromElement(element);
+  replaceFormulaElement(element, `${latex}+1`);
+}
+```
+
+生成的公式节点会将 LaTeX 源内容保存在 `data-formulax-latex` 中，并通过 `data-formulax="true"` 标记：
+
+```html
+<span
+  class="formulax-math"
+  data-formulax="true"
+  data-formulax-latex="\\sqrt{x}"
+  data-latex="\\sqrt{x}"
+  contenteditable="false"
+  data-mce-contenteditable="false"
+  style="cursor: pointer"
+></span>
+```
+
+具体生成的 HTML 结构属于内部实现，后续可能演进。业务侧应优先依赖导出的工具函数。
+
+## 配置项
+
+```ts
+interface FormulaXTinyMceOptions {
+  pluginName?: string;
+  buttonName?: string;
+  menuItemName?: string;
+  toolbarText?: string;
+  tooltip?: string;
+  cursorStyle?: string;
+  formulaClassName?: string;
+  formulaAttributeName?: string;
+  renderMode?: 'text' | 'html';
+  initialLatex?: string;
+  modal?: FormulaXModalOptions;
+  editor?: FormulaXEditorOptions;
+}
+```
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `pluginName` | `formulax` | 通过 `tinymce.PluginManager.add` 注册的 TinyMCE 插件名。 |
+| `buttonName` | `formulax` | 工具栏按钮名。 |
+| `menuItemName` | `formulax` | 菜单项名。 |
+| `toolbarText` | `FormulaX` | 工具栏按钮和菜单项显示文本。 |
+| `tooltip` | `Insert formula` | 工具栏按钮 tooltip。 |
+| `cursorStyle` | `pointer` | 应用于生成公式节点的鼠标光标样式。 |
+| `formulaClassName` | `formulax-math` | 生成的公式节点 CSS class。 |
+| `formulaAttributeName` | `data-formulax-latex` | 用于保存 LaTeX 源内容的属性。 |
+| `renderMode` | `text` | 实验性的渲染模式配置。 |
+| `initialLatex` | 空字符串 | 插入新公式时的初始 LaTeX。 |
+| `modal` | 见下方 | 弹窗标题、按钮文本、尺寸和关闭行为。 |
+| `editor` | 见下方 | 内嵌 FormulaX 编辑器配置。 |
+
+### Modal 配置
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `title` | `FormulaX` | 弹窗标题。 |
+| `insertText` | `Insert` | 插入公式时的提交按钮文本。 |
+| `updateText` | `Update` | 更新公式时的提交按钮文本。 |
+| `cancelText` | `Cancel` | 取消按钮文本。 |
+| `width` | `1100px` | 弹窗宽度。 |
+| `height` | `auto` | 弹窗高度。 |
+| `closeOnBackdrop` | `true` | 点击遮罩层时是否关闭弹窗。 |
+
+### Editor 配置
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `mode` | `kity` | 公式编辑器运行时模式。 |
+| `height` | `100%` | 内嵌编辑器高度。 |
+| `autofocus` | `true` | 内嵌编辑器是否自动聚焦。 |
+| `assets` | `{}` | 可选的 Kity runtime 资源覆盖配置。 |
+| `render.fontsize` | `40` | 公式渲染字号。 |
+
+## 导出 API
+
+| 导出 | 说明 |
+| --- | --- |
+| `registerFormulaXTinyMcePlugin` | 注册 TinyMCE 插件。 |
+| `resolveOptions` | 将用户配置与默认配置合并为完整配置。 |
+| `openFormulaXOverlayModal` | 直接打开 FormulaX 弹窗。 |
+| `createTinyMceFormulaMarkup` | 根据 LaTeX 创建公式 HTML。 |
+| `parseTinyMceFormulaMarkup` | 将 LaTeX 解析为 FormulaX 文档。 |
+| `serializeTinyMceFormulaMarkup` | 将 FormulaX 文档序列化为 TinyMCE 公式 HTML。 |
+| `getFormulaLatexFromElement` | 从公式元素读取 LaTeX 源内容。 |
+| `findFormulaElement` | 查找最近的 FormulaX 公式元素。 |
+| `isFormulaElement` | 判断节点是否为 FormulaX 公式元素。 |
+| `replaceFormulaElement` | 使用更新后的 markup 替换已有公式元素。 |
+| `getTinyMceMajorVersion` | 读取 TinyMCE 主版本号。 |
+| `createTinyMceCompat` | 创建内部 TinyMCE 兼容门面。 |
+| `warnUnsupportedTinyMceVersion` | 对不支持的 TinyMCE 版本输出警告。 |
+
+## 开发
+
+在仓库根目录执行：
+
+```bash
+pnpm install
+pnpm dev:tinymce
+```
+
+仅构建该包：
+
+```bash
+pnpm --filter @formulaxjs/tinymce build
+```
+
+运行该包测试：
+
+```bash
+pnpm --filter @formulaxjs/tinymce test
+```
+
+运行该包类型检查：
+
+```bash
+pnpm --filter @formulaxjs/tinymce typecheck
+```
+
+## Demo
+
+本地 demo：
+
+```bash
+pnpm dev:tinymce
+```
+
+GitHub Pages demo：
+
+[https://vndmea.github.io/formulaX/tinymce/](https://vndmea.github.io/formulaX/tinymce/)
+
+该 demo 包含 TinyMCE 版本选择器，并目标上尽量与独立 FormulaX playground 的体验保持一致。
+
+## 注意事项与限制
+
+- TinyMCE 5 以下以及 9 或更高版本目前不是官方支持范围。
+- 当前 API 仍处于实验阶段。
+- 如果宿主 TinyMCE 配置了严格的内容过滤，需要确保允许 FormulaX 公式 span 和 SVG 输出。
+- 当前编辑 UI 使用 FormulaX 的 Kity 兼容运行时。
+
+## 协议
+
+FormulaX 的许可信息应在公开 npm 发布前完成审查。
+
+KityFormula 相关代码和资源保留其原始版权和许可声明。