@formulaxjs/tiptap 0.3.0 → 0.4.0

package/README.md

@@ -1,73 +1,76 @@
-# @formulaxjs/tiptap
-
-English | [简体中文](./README.zh-CN.md)
-
-Tiptap integration adapter for FormulaX.
-
-`@formulaxjs/tiptap` provides a FormulaX inline node extension for Tiptap and a modal-based formula editing flow. The extension persists only LaTeX in the document model and renders formula output at runtime through the shared FormulaX renderer interface.
-
-> Status: experimental. Public APIs may change before the first stable release.
-
-## Features
-
-- Tiptap node extension export through `FormulaXNode`
-- Extension factory export through `createFormulaXNode`
-- `openFormulaX` command for toolbar buttons or programmatic opening
-- Double-click editing for existing formulas
-- Persist only LaTeX in node attrs
-- Runtime SVG rendering in the node view
-- Default read-only rendering through `@formulaxjs/renderer-kity`
-- Optional runtime preload before the first modal open
-- Modal helper export through `openFormulaXTiptapModal`
-- Compatible peer dependency range for Tiptap 2 and 3
-
-## Compatibility
-
-The package declares `@tiptap/core` as an optional peer dependency:
-
-```json
-{
-  "@tiptap/core": ">=2 <4"
-}
-```
-
-The workspace demo can switch between Tiptap 2 and 3 for compatibility verification.
-
-## Install
-
-When the package is published:
-
-```bash
-pnpm add @formulaxjs/tiptap
-pnpm add @tiptap/core
-```
-
-Inside the FormulaX workspace, use the workspace package directly:
-
-```bash
-pnpm install
-pnpm dev:tiptap
-```
-
-## Basic usage
-
-Create the FormulaX node extension and add it to the Tiptap extension list:
-
-```ts
-import { Editor } from '@tiptap/core';
-import StarterKit from '@tiptap/starter-kit';
-import { createFormulaXNode } from '@formulaxjs/tiptap';
-
+# @formulaxjs/tiptap
+
+English | [简体中文](https://github.com/vndmea/formulaX/blob/main/packages/tiptap/README.zh-CN.md)
+
+Tiptap integration adapter for FormulaX.
+
+`@formulaxjs/tiptap` provides a FormulaX inline node extension for Tiptap and a modal-based formula editing flow. The extension persists only LaTeX in the document model and renders formula output at runtime through the shared FormulaX renderer interface.
+
+> Status: experimental. Public APIs may change before the first stable release.
+
+## Features
+
+- Tiptap node extension export through `FormulaXNode`
+- Extension factory export through `createFormulaXNode`
+- `openFormulaX` command for toolbar buttons or programmatic opening
+- Double-click editing for existing formulas
+- Persist only LaTeX in node attrs
+- Runtime SVG rendering in the node view
+- Default read-only rendering through `@formulaxjs/renderer-kity`
+- Optional runtime preload before the first modal open
+- Modal helper export through `openFormulaXTiptapModal`
+- Compatible peer dependency range for Tiptap 2 and 3
+
+## Compatibility
+
+The package declares `@tiptap/core` as an optional peer dependency:
+
+```json
+{
+  "@tiptap/core": ">=2 <4"
+}
+```
+
+The workspace demo can switch between Tiptap 2 and 3 for compatibility verification.
+
+## Install
+
+When the package is published:
+
+```bash
+npm install @formulaxjs/tiptap @tiptap/core
+```
+
+Inside the FormulaX workspace, use the workspace package directly:
+
+```bash
+pnpm install
+pnpm dev:tiptap
+```
+
+## Basic usage
+
+Create the FormulaX node extension and add it to the Tiptap extension list:
+
+```ts
+import { Editor } from '@tiptap/core';
+import StarterKit from '@tiptap/starter-kit';
+import { createFormulaXNode } from '@formulaxjs/tiptap';
+
 const editor = new Editor({
   element: document.querySelector('#editor')!,
   extensions: [
     StarterKit,
-    createFormulaXNode(),
+    createFormulaXNode(undefined, {
+      editor: {
+        locale: 'zh_CN', // optional, defaults to en_US
+      },
+    }),
   ],
   content: '<p>Click the toolbar button to insert a formula.</p>',
 });
 ```
-
+
 To open the FormulaX modal programmatically:
 
 ```ts
@@ -75,162 +78,164 @@ editor.commands.openFormulaX();
 ```
 
 ## Custom node names
-
-The default Tiptap node name is `formulaX`.
-
-If the host editor already uses that name, pass a custom `name` when creating the extension:
-
-```ts
-const editor = new Editor({
-  element: document.querySelector('#editor')!,
-  extensions: [
-    StarterKit,
-    createFormulaXNode(undefined, {
-      name: 'inlineMath',
-    }),
-  ],
-});
-```
-
-If Tiptap detects that the configured node name is already registered, the extension logs a `console.warn` message so you can rename it before the schema collides.
-
-## Persisted data
-
-The Tiptap node stores only the LaTeX source:
-
-```json
-{
-  "type": "formulaX",
-  "attrs": {
-    "latex": "\\sqrt{x}"
-  }
-}
-```
-
-The node view renders formula SVG at runtime from the stored LaTeX. Generated DOM markup includes `data-formulax="true"` and `data-formulax-latex`, but that rendered DOM is not the persisted source of truth.
-
-## Custom renderer
-
-The adapter accepts a `renderer` option. By default it uses `createKityFormulaRenderer()` from `@formulaxjs/renderer-kity`.
-
-```ts
-import { createFormulaXNode } from '@formulaxjs/tiptap';
-import { createKityFormulaRenderer } from '@formulaxjs/renderer-kity';
-
-const formulaNode = createFormulaXNode(undefined, {
+
+The default Tiptap node name is `formulaX`.
+
+If the host editor already uses that name, pass a custom `name` when creating the extension:
+
+```ts
+const editor = new Editor({
+  element: document.querySelector('#editor')!,
+  extensions: [
+    StarterKit,
+    createFormulaXNode(undefined, {
+      name: 'inlineMath',
+    }),
+  ],
+});
+```
+
+If Tiptap detects that the configured node name is already registered, the extension logs a `console.warn` message so you can rename it before the schema collides.
+
+## Persisted data
+
+The Tiptap node stores only the LaTeX source:
+
+```json
+{
+  "type": "formulaX",
+  "attrs": {
+    "latex": "\\sqrt{x}"
+  }
+}
+```
+
+The node view renders formula SVG at runtime from the stored LaTeX. Generated DOM markup includes `data-formulax="true"` and `data-formulax-latex`, but that rendered DOM is not the persisted source of truth.
+
+## Custom renderer
+
+The adapter accepts a `renderer` option. By default it uses `createKityFormulaRenderer()` from `@formulaxjs/renderer-kity`.
+
+```ts
+import { createFormulaXNode } from '@formulaxjs/tiptap';
+import { createKityFormulaRenderer } from '@formulaxjs/renderer-kity';
+
+const formulaXNode = createFormulaXNode(undefined, {
   renderer: createKityFormulaRenderer({
     fontSize: 44,
   }),
 });
-```
-
-## Options
-
-```ts
-interface FormulaXTiptapOptions {
-  name?: string;
-  formulaClassName?: string;
-  formulaAttributeName?: string;
-  cursorStyle?: string;
-  initialLatex?: string;
-  renderer?: FormulaRenderer;
-  preload?: FormulaXEditorPreloadMode;
-  modal?: {
-    title?: string;
-    insertText?: string;
-    updateText?: string;
-    cancelText?: string;
-    closeOnBackdrop?: boolean;
-  };
+```
+
+## Options
+
+```ts
+interface FormulaXTiptapOptions {
+  name?: string;
+  formulaClassName?: string;
+  formulaAttributeName?: string;
+  cursorStyle?: string;
+  initialLatex?: string;
+  renderer?: FormulaRenderer;
+  preload?: FormulaXEditorPreloadMode;
+  modal?: {
+    title?: string;
+    insertText?: string;
+    updateText?: string;
+    cancelText?: string;
+    closeOnBackdrop?: boolean;
+  };
   editor?: {
     height?: number | string;
     autofocus?: boolean;
+    locale?: FormulaXLocale;
     assets?: Partial<KityEditorAssets>;
     render?: {
       fontsize?: number;
-    };
-  };
-}
-```
-
-| Option | Default | Description |
-| --- | --- | --- |
-| `name` | `formulaX` | Tiptap node name used in the document schema. |
-| `formulaClassName` | `formulax-math` | CSS class used by rendered formula nodes. |
-| `formulaAttributeName` | `data-formulax-latex` | Attribute used in rendered DOM for the source LaTeX. |
-| `cursorStyle` | `pointer` | Cursor style applied to rendered formula nodes. |
-| `initialLatex` | empty string | Initial LaTeX when inserting a new formula. |
-| `renderer` | `createKityFormulaRenderer()` | Renderer used for read-only formula output in the node view. |
-| `preload` | `idle` | Preloads the FormulaX runtime on browser idle, on host hover/focus, or never. |
-| `modal` | see below | Modal labels and closing behavior. |
-| `editor` | see below | Embedded FormulaX editor options. |
-
-### Modal options
-
-| Option | Default | Description |
-| --- | --- | --- |
-| `title` | `FormulaX Editor` | Modal title. |
-| `insertText` | `Insert` | Submit button text when inserting. |
-| `updateText` | `Update` | Submit button text when updating. |
-| `cancelText` | `Cancel` | Cancel button text. |
-| `closeOnBackdrop` | `true` | Whether clicking the backdrop closes the modal. |
-
-### Editor options
-
-| Option | Default | Description |
-| --- | --- | --- |
+    };
+  };
+}
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `name` | `formulaX` | Tiptap node name used in the document schema. |
+| `formulaClassName` | `formulax-math` | CSS class used by rendered formula nodes. |
+| `formulaAttributeName` | `data-formulax-latex` | Attribute used in rendered DOM for the source LaTeX. |
+| `cursorStyle` | `pointer` | Cursor style applied to rendered formula nodes. |
+| `initialLatex` | empty string | Initial LaTeX when inserting a new formula. |
+| `renderer` | `createKityFormulaRenderer()` | Renderer used for read-only formula output in the node view. |
+| `preload` | `idle` | Preloads the FormulaX runtime on browser idle, on host hover/focus, or never. |
+| `modal` | see below | Modal labels and closing behavior. |
+| `editor` | see below | Embedded FormulaX editor options. |
+
+### Modal options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `title` | `FormulaX Editor` | Modal title. |
+| `insertText` | `Insert` | Submit button text when inserting. |
+| `updateText` | `Update` | Submit button text when updating. |
+| `cancelText` | `Cancel` | Cancel button text. |
+| `closeOnBackdrop` | `true` | Whether clicking the backdrop closes the modal. |
+
+### Editor options
+
+| Option | Default | Description |
+| --- | --- | --- |
 | `height` | `100%` | Embedded editor height. |
 | `autofocus` | `true` | Whether the embedded editor should autofocus. |
+| `locale` | `en_US` | Localizes the modal defaults and the embedded Kity runtime UI. |
 | `assets` | `{}` | Optional Kity runtime asset overrides. |
 | `render.fontsize` | `40` | Formula render font size. |
-
-## Exported API
-
-| Export | Description |
-| --- | --- |
-| `FormulaXNode` | Default FormulaX Tiptap node extension. |
-| `createFormulaXNode` | Creates a FormulaX node extension, optionally with custom options. |
-| `resolveOptions` | Resolves user options into required defaults. |
-| `openFormulaXTiptapModal` | Opens the FormulaX modal directly. |
-| `FORMULAX_NODE_NAME` | Default Tiptap node name. |
-| `createFormulaXPayload` | Parses LaTeX into a FormulaX document. |
-| `serializeFormulaXPayload` | Serializes a FormulaX document back to LaTeX. |
-
-## Development
-
-From the repository root:
-
-```bash
-pnpm install
-pnpm dev:tiptap
-```
-
-Build only this package:
-
-```bash
-pnpm --filter @formulaxjs/tiptap build
-```
-
-Run package tests:
-
-```bash
-pnpm --filter @formulaxjs/tiptap test
-```
-
-Run package type checking:
-
-```bash
-pnpm --filter @formulaxjs/tiptap typecheck
-```
-
-## Demo
-
-Local demo:
-
-```bash
-pnpm dev:tiptap
-```
-
-GitHub Pages demo:
-
-[https://vndmea.github.io/formulaX/tiptap/](https://vndmea.github.io/formulaX/tiptap/)
+
+## Exported API
+
+| Export | Description |
+| --- | --- |
+| `FormulaXNode` | Default FormulaX Tiptap node extension. |
+| `createFormulaXNode` | Creates a FormulaX node extension, optionally with custom options. |
+| `resolveOptions` | Resolves user options into required defaults. |
+| `openFormulaXTiptapModal` | Opens the FormulaX modal directly. |
+| `FORMULAX_NODE_NAME` | Default Tiptap node name. |
+| `createFormulaXPayload` | Parses LaTeX into a FormulaX document. |
+| `serializeFormulaXPayload` | Serializes a FormulaX document back to LaTeX. |
+
+## Development
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm dev:tiptap
+```
+
+Build only this package:
+
+```bash
+pnpm --filter @formulaxjs/tiptap build
+```
+
+Run package tests:
+
+```bash
+pnpm --filter @formulaxjs/tiptap test
+```
+
+Run package type checking:
+
+```bash
+pnpm --filter @formulaxjs/tiptap typecheck
+```
+
+## Demo
+
+Local demo:
+
+```bash
+pnpm dev:tiptap
+```
+
+GitHub Pages demo:
+
+[https://vndmea.github.io/formulaX/tiptap/](https://vndmea.github.io/formulaX/tiptap/)

package/README.zh-CN.md

@@ -1,10 +1,10 @@
 # @formulaxjs/tiptap
 
-[English](./README.md) | 简体中文
+[English](https://github.com/vndmea/formulaX/blob/main/packages/tiptap/README.md) | 简体中文
 
 FormulaX 的 Tiptap 集成适配器。
 
-`@formulaxjs/tiptap` 提供了一个 FormulaX 行内节点扩展和基于弹窗的公式编辑流程。该扩展在文档模型中只持久化 LaTeX，并通过共享的 FormulaX renderer 接口在运行时渲染公式展示结果。
+`@formulaxjs/tiptap` 提供了一个 FormulaX 行内节点扩展和基于弹窗的公式编辑流程。该扩展在文档模型中只持久化 LaTeX，并通过共享的 FormulaX renderer 接口在运行时渲染公式展示结果。
 
 > 状态：实验阶段。在首个稳定版本发布前，公共 API 仍可能调整。
 
@@ -13,13 +13,13 @@ FormulaX 的 Tiptap 集成适配器。
 - 通过 `FormulaXNode` 导出 Tiptap 节点扩展
 - 通过 `createFormulaXNode` 导出扩展工厂函数
 - 提供 `openFormulaX` 命令，便于接工具栏按钮或代码中主动打开
-- 支持双击编辑已有公式
-- 节点 attrs 中仅持久化 LaTeX
-- 在 node view 中运行时渲染 SVG
-- 默认通过 `@formulaxjs/renderer-kity` 完成只读渲染
-- 支持在首次打开弹窗前预加载 runtime
-- 直接导出弹窗工具函数 `openFormulaXTiptapModal`
-- 兼容 Tiptap 2 和 3 的 peer dependency 范围
+- 支持双击编辑已有公式
+- 节点 attrs 中仅持久化 LaTeX
+- 在 node view 中运行时渲染 SVG
+- 默认通过 `@formulaxjs/renderer-kity` 完成只读渲染
+- 支持在首次打开弹窗前预加载 runtime
+- 直接导出弹窗工具函数 `openFormulaXTiptapModal`
+- 兼容 Tiptap 2 和 3 的 peer dependency 范围
 
 ## 兼容性
 
@@ -38,8 +38,7 @@ FormulaX 的 Tiptap 集成适配器。
 包发布后可使用：
 
 ```bash
-pnpm add @formulaxjs/tiptap
-pnpm add @tiptap/core
+npm install @formulaxjs/tiptap @tiptap/core
 ```
 
 在 FormulaX 工作空间内，直接使用 workspace 包：
@@ -58,23 +57,27 @@ import { Editor } from '@tiptap/core';
 import StarterKit from '@tiptap/starter-kit';
 import { createFormulaXNode } from '@formulaxjs/tiptap';
 
-const editor = new Editor({
-  element: document.querySelector('#editor')!,
-  extensions: [
-    StarterKit,
-    createFormulaXNode(),
-  ],
-  content: '<p>点击工具栏按钮插入公式。</p>',
-});
-```
-
-如果要在代码中主动打开 FormulaX 弹窗：
-
-```ts
-editor.commands.openFormulaX();
-```
+const editor = new Editor({
+  element: document.querySelector('#editor')!,
+  extensions: [
+    StarterKit,
+    createFormulaXNode(undefined, {
+      editor: {
+        locale: 'zh_CN', // 可选，默认 en_US
+      },
+    }),
+  ],
+  content: '<p>点击工具栏按钮插入公式。</p>',
+});
+```
 
-## 自定义节点名称
+如果要在代码中主动打开 FormulaX 弹窗：
+
+```ts
+editor.commands.openFormulaX();
+```
+
+## 自定义节点名称
 
 默认的 Tiptap 节点名是 `formulaX`。
 
@@ -107,47 +110,48 @@ Tiptap 节点中只保存 LaTeX 源内容：
 }
 ```
 
-节点视图会根据保存的 LaTeX 在运行时渲染 SVG。生成的 DOM 会带有 `data-formulax="true"` 和 `data-formulax-latex`，但这些渲染后的 DOM 不是持久化数据的真实来源。
-
-## 自定义 renderer
-
-该适配器支持 `renderer` 配置项。默认值是来自 `@formulaxjs/renderer-kity` 的 `createKityFormulaRenderer()`。
-
-```ts
-import { createFormulaXNode } from '@formulaxjs/tiptap';
-import { createKityFormulaRenderer } from '@formulaxjs/renderer-kity';
-
-const formulaNode = createFormulaXNode(undefined, {
+节点视图会根据保存的 LaTeX 在运行时渲染 SVG。生成的 DOM 会带有 `data-formulax="true"` 和 `data-formulax-latex`，但这些渲染后的 DOM 不是持久化数据的真实来源。
+
+## 自定义 renderer
+
+该适配器支持 `renderer` 配置项。默认值是来自 `@formulaxjs/renderer-kity` 的 `createKityFormulaRenderer()`。
+
+```ts
+import { createFormulaXNode } from '@formulaxjs/tiptap';
+import { createKityFormulaRenderer } from '@formulaxjs/renderer-kity';
+
+const formulaXNode = createFormulaXNode(undefined, {
   renderer: createKityFormulaRenderer({
     fontSize: 44,
   }),
 });
-```
+```
 
 ## 配置项
 
 ```ts
-interface FormulaXTiptapOptions {
-  name?: string;
-  formulaClassName?: string;
-  formulaAttributeName?: string;
-  cursorStyle?: string;
-  initialLatex?: string;
-  renderer?: FormulaRenderer;
-  preload?: FormulaXEditorPreloadMode;
-  modal?: {
-    title?: string;
-    insertText?: string;
+interface FormulaXTiptapOptions {
+  name?: string;
+  formulaClassName?: string;
+  formulaAttributeName?: string;
+  cursorStyle?: string;
+  initialLatex?: string;
+  renderer?: FormulaRenderer;
+  preload?: FormulaXEditorPreloadMode;
+  modal?: {
+    title?: string;
+    insertText?: string;
     updateText?: string;
     cancelText?: string;
     closeOnBackdrop?: boolean;
   };
-  editor?: {
-    height?: number | string;
-    autofocus?: boolean;
-    assets?: Partial<KityEditorAssets>;
-    render?: {
-      fontsize?: number;
+  editor?: {
+    height?: number | string;
+    autofocus?: boolean;
+    locale?: FormulaXLocale;
+    assets?: Partial<KityEditorAssets>;
+    render?: {
+      fontsize?: number;
     };
   };
 }
@@ -158,12 +162,12 @@ interface FormulaXTiptapOptions {
 | `name` | `formulaX` | 用于文档 schema 的 Tiptap 节点名。 |
 | `formulaClassName` | `formulax-math` | 渲染后公式节点使用的 CSS class。 |
 | `formulaAttributeName` | `data-formulax-latex` | 渲染后 DOM 中保存 LaTeX 源内容的属性名。 |
-| `cursorStyle` | `pointer` | 渲染后公式节点的鼠标光标样式。 |
-| `initialLatex` | 空字符串 | 插入新公式时的初始 LaTeX。 |
-| `renderer` | `createKityFormulaRenderer()` | node view 中用于只读公式输出的 renderer。 |
-| `preload` | `idle` | 控制在浏览器空闲时、宿主 hover/focus 时，或完全不预加载 FormulaX runtime。 |
-| `modal` | 见下方 | 弹窗文案和关闭行为。 |
-| `editor` | 见下方 | 内嵌 FormulaX 编辑器配置。 |
+| `cursorStyle` | `pointer` | 渲染后公式节点的鼠标光标样式。 |
+| `initialLatex` | 空字符串 | 插入新公式时的初始 LaTeX。 |
+| `renderer` | `createKityFormulaRenderer()` | node view 中用于只读公式输出的 renderer。 |
+| `preload` | `idle` | 控制在浏览器空闲时、宿主 hover/focus 时，或完全不预加载 FormulaX runtime。 |
+| `modal` | 见下方 | 弹窗文案和关闭行为。 |
+| `editor` | 见下方 | 内嵌 FormulaX 编辑器配置。 |
 
 ### Modal 配置
 
@@ -179,10 +183,11 @@ interface FormulaXTiptapOptions {
 
 | 配置项 | 默认值 | 说明 |
 | --- | --- | --- |
-| `height` | `100%` | 内嵌编辑器高度。 |
-| `autofocus` | `true` | 内嵌编辑器是否自动聚焦。 |
-| `assets` | `{}` | 可选的 Kity runtime 资源覆盖配置。 |
-| `render.fontsize` | `40` | 公式渲染字号。 |
+| `height` | `100%` | 内嵌编辑器高度。 |
+| `autofocus` | `true` | 内嵌编辑器是否自动聚焦。 |
+| `locale` | `en_US` | 同时切换弹窗默认文案和内嵌 Kity runtime UI。 |
+| `assets` | `{}` | 可选的 Kity runtime 资源覆盖配置。 |
+| `render.fontsize` | `40` | 公式渲染字号。 |
 
 ## 导出 API