@naersen/tts-rich-text 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 naersen
+
+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,166 @@
+# @naersen/tts-rich-text
+
+面向 Vue 3 项目的 TTS 富文本编辑器。包内维护统一的 Tiptap 文档协议、TTS 标签、分句和数据转换；各业务项目通过 `features`、`services` 和 slots 注入差异，不再复制组件源码。
+
+## 环境要求
+
+- Vue 3.4+
+- Node.js 18+
+- pnpm 9+
+
+## 本地开发
+
+```bash
+pnpm install
+pnpm dev
+```
+
+开发预览默认运行在 Vite 输出的本地地址。提交前执行：
+
+```bash
+pnpm build
+pnpm test:e2e
+```
+
+`build` 会依次完成类型检查、单元测试和组件库构建。`test:e2e` 使用本机 Chrome 验证拼音标注、停顿插入、原主题样式和窄屏工具栏收纳。
+
+## 安装
+
+通过 npm 在业务项目中安装：
+
+```bash
+pnpm add @naersen/tts-rich-text
+```
+
+Vue、Tiptap 和 Element Plus 是 peer dependencies。业务项目没有安装时，需要同时添加 peer packages，并在应用入口加载 Element Plus 样式。
+
+## 基础使用
+
+```vue
+<template>
+	<tts-rich-text-editor
+		v-model="documentValue"
+		:voice-version="voiceVersion"
+		:features="features"
+		:services="services"
+		:get-preview-params="getPreviewParams"
+	/>
+</template>
+
+<script setup lang="ts">
+import type { JSONContent } from '@tiptap/core'
+import { ref } from 'vue'
+
+import type {
+	TtsEditorFeatures,
+	TtsRichTextServices
+} from '@naersen/tts-rich-text'
+import {
+	TtsRichTextEditor,
+	getInitContent
+} from '@naersen/tts-rich-text'
+import '@naersen/tts-rich-text/styles.css'
+
+const documentValue = ref<JSONContent>(getInitContent())
+const voiceVersion = ref(2)
+
+const features: TtsEditorFeatures = {
+	tools: ['stop', 'customStop', 'pinyin', 'replace', 'language'],
+	enablePreview: true
+}
+
+const services: TtsRichTextServices = {
+	parseDocument: async (file, signal) => {
+		return api.parseDocument(file, { signal })
+	},
+	readFormula: async (formula, { signal, onChunk }) => {
+		return api.readFormula(formula, { signal, onChunk })
+	},
+	synthesizePreview: async (request, signal) => {
+		return api.synthesizePreview(request, { signal })
+	},
+	notify: (type, message) => messageService[type](message)
+}
+
+const getPreviewParams = () => ({
+	timberId: selectedVoice.value.id,
+	speed: selectedVoice.value.speed
+})
+</script>
+```
+
+`styles.css` 已包含原项目的 Element Plus 全局主题覆盖和配套图标；业务项目仍需先加载 `element-plus/dist/index.css`，再加载组件库样式。
+
+上例中的 `api`、`messageService` 和 `selectedVoice` 由业务项目提供，组件包不会读取业务项目的环境变量、请求实例或状态管理。
+
+## 差异扩展
+
+### 功能配置
+
+`features` 可以覆盖工具列表、语言列表、拼音最大选区长度、数字最大长度和试听开关。包内提供 V1/V2 默认能力配置，项目配置拥有最高优先级。
+
+### 服务适配
+
+以下能力只有传入对应 service 时才可用；未提供时保留原工具位置并显示为禁用态：
+
+- `parseDocument`：上传并解析 TXT/DOCX。
+- `generateDraft`：AI 写稿，支持通过 `onChunk` 增量输出。
+- `readFormula`：公式转读法，支持通过 `onChunk` 增量输出。
+- `synthesizePreview`：选区试听，返回音频 URL 或 Blob。
+- `synthesizePreviewStream`：保持原编辑器的流式分片试听，逐条调用 `onMessage` 传入后端音频消息。
+- `confirmVoiceChange`：接管音色版本冲突确认框；未提供时使用 Element Plus。
+- `notify`：接入项目自己的消息组件。
+
+所有耗时服务都会收到 `AbortSignal`，项目请求层必须将取消信号继续传给实际请求。
+
+### Slots
+
+- `toolbar-before`
+- `toolbar-after`
+- `editor-after`，参数为 `{ editor }`
+- `footer-before`，参数为 `{ editor, textLength }`
+- `footer-after`，参数为 `{ editor, textLength }`
+
+项目专属工具应通过 slots 放在组件外层，不能修改包内工具栏源码。
+
+### 原子组件
+
+对编辑器外壳差异较大的项目，可以直接组合包内原始组件：
+
+- `TtsEditorToolbar`
+- `TtsEditorFooter`
+- `TtsSelectionMenu`
+- `TtsMarkPinyinModal`
+- `TtsTagNodeView`
+- `TtsAiRewriteModal`
+- `TtsFormulaModal`
+- `TtsReplaceTextModal`
+- `TtsUploadModal`
+
+这些组件与 `useRichTextEditor`、`useEditorProvider` 使用同一个上下文。优先使用完整的 `TtsRichTextEditor`；只有页面布局确实不同的项目才自行组合原子组件，业务接口仍统一通过 `services` 注入。
+
+## 对外方法
+
+通过组件 ref 可以调用：
+
+- `clear()`
+- `focus()`
+- `getJson()`
+- `getTtsData()`
+- `replaceText(text)`
+
+核心转换函数也可以独立导入：
+
+```ts
+import { convertToTtsFormat } from '@naersen/tts-rich-text/core'
+```
+
+## 版本管理
+
+遵循 SemVer：
+
+- 修复兼容问题：patch，例如 `0.1.1`。
+- 增加向后兼容能力：minor，例如 `0.2.0`。
+- 修改文档协议、TTS 输出或删除公开 API：major。
+
+项目应依赖明确版本，通过升级依赖完成同步，不要把 `src` 目录复制回业务项目。

package/dist/components/cx-button/index.d.ts

@@ -0,0 +1,9 @@
+import { ElButton } from 'element-plus';
+import { default as CxButton } from './index.vue';
+export type ButtonInstance = InstanceType<typeof CxButton>;
+declare module 'vue' {
+    interface GlobalComponents {
+        CxButton: typeof ElButton;
+    }
+}
+export default CxButton;

package/dist/components/cx-button/index.vue.d.ts

@@ -0,0 +1,20 @@
+type __VLS_Props = {
+    link?: boolean;
+};
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: Partial<Record<string, (_: any) => any>>;
+    refs: {};
+    rootEl: any;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    link: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/cx-empty/index.d.ts

@@ -0,0 +1,2 @@
+import { default as CxEmpty } from './index.vue';
+export default CxEmpty;

package/dist/components/cx-empty/index.vue.d.ts

@@ -0,0 +1,26 @@
+type __VLS_Props = {
+    description?: string;
+    size?: number;
+    type?: 'normal' | 'search';
+};
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        icon?(_: {}): any;
+    };
+    refs: {};
+    rootEl: HTMLDivElement;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    type: "normal" | "search";
+    size: number;
+    description: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/cx-radio-group/index.d.ts

@@ -0,0 +1,3 @@
+import { default as CxRadioGroup } from './index.vue';
+export * from './type';
+export default CxRadioGroup;

package/dist/components/cx-radio-group/index.vue.d.ts

@@ -0,0 +1,19 @@
+import { RadioProps, RadioValue } from './type';
+declare const _default: import('vue').DefineComponent<RadioProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    "update:modelValue": (value: RadioValue) => any;
+    change: (value: RadioValue) => any;
+}, string, import('vue').PublicProps, Readonly<RadioProps> & Readonly<{
+    "onUpdate:modelValue"?: ((value: RadioValue) => any) | undefined;
+    onChange?: ((value: RadioValue) => any) | undefined;
+}>, {
+    color: string;
+    modelValue: RadioValue;
+    defaultValue: RadioValue;
+    options: import('./type').RadioOption[];
+    hoverColor: string;
+    activeColor: string;
+    background: string;
+    hoverBackground: string;
+    activeBackgound: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/dist/components/cx-radio-group/type/index.d.ts

@@ -0,0 +1,25 @@
+import { CSSProperties } from 'vue';
+export interface RadioProps {
+    modelValue?: RadioValue;
+    defaultValue?: RadioValue;
+    options?: RadioOption[];
+    color?: string;
+    hoverColor?: string;
+    activeColor?: string;
+    background?: string;
+    hoverBackground?: string;
+    activeBackgound?: string;
+    sliderStyle?: CSSProperties;
+    radioStyle?: CSSProperties;
+}
+export interface RadioEmits {
+    (e: 'update:modelValue', value: RadioValue): void;
+    (e: 'change', value: RadioValue): void;
+}
+export interface RadioOption {
+    label?: string;
+    value: RadioValue;
+    icon?: string;
+    iconSize?: number;
+}
+export type RadioValue = string | number;

package/dist/components/cx-spin/index.d.ts

@@ -0,0 +1,3 @@
+import { default as CxSpin } from './index.vue';
+export type SpinInstance = InstanceType<typeof CxSpin>;
+export default CxSpin;

package/dist/components/cx-spin/index.vue.d.ts

@@ -0,0 +1,26 @@
+type __VLS_Props = {
+    loading?: boolean;
+    text?: string;
+    size?: number;
+};
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {}): any;
+    };
+    refs: {};
+    rootEl: HTMLDivElement;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    size: number;
+    text: string;
+    loading: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/cx-upload/index.d.ts

@@ -0,0 +1,3 @@
+import { default as CxUpload } from './index.vue';
+export type UploadInstance = InstanceType<typeof CxUpload>;
+export default CxUpload;

package/dist/components/cx-upload/index.vue.d.ts

@@ -0,0 +1,43 @@
+import { UploadProps } from './type';
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        operate?(_: {}): any;
+    };
+    refs: {
+        uploadRef: HTMLDivElement;
+    };
+    rootEl: HTMLDivElement;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<UploadProps, {
+    open: () => void;
+    clear: () => void;
+}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    clear: () => any;
+    "update:modelValue": (value: File[]) => any;
+    change: (value: File[]) => any;
+    error: (type: "type" | "size", file: File) => any;
+}, string, import('vue').PublicProps, Readonly<UploadProps> & Readonly<{
+    onClear?: (() => any) | undefined;
+    "onUpdate:modelValue"?: ((value: File[]) => any) | undefined;
+    onChange?: ((value: File[]) => any) | undefined;
+    onError?: ((type: "type" | "size", file: File) => any) | undefined;
+}>, {
+    title: string;
+    disabled: boolean;
+    modelValue: File[];
+    defaultValue: File[];
+    accept: string[];
+    maxSize: number;
+    tip: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    uploadRef: HTMLDivElement;
+}, HTMLDivElement>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/cx-upload/type/index.d.ts

@@ -0,0 +1,15 @@
+export interface UploadProps {
+    modelValue?: File[];
+    defaultValue?: File[];
+    accept?: string[];
+    maxSize?: number;
+    disabled?: boolean;
+    title?: string;
+    tip?: string;
+}
+export interface UploadEmits {
+    (e: 'update:modelValue', value: File[]): void;
+    (e: 'change', value: File[]): void;
+    (e: 'error', type: 'type' | 'size', file: File): void;
+    (e: 'clear'): void;
+}

package/dist/components/index.d.ts

@@ -0,0 +1,8 @@
+export { default as CxButton } from './cx-button';
+export { default as CxEmpty } from './cx-empty';
+export { default as CxRadioGroup } from './cx-radio-group';
+export { default as CxSpin } from './cx-spin';
+export { default as CxUpload } from './cx-upload';
+export { default as SvgIcon } from './svg-icon';
+export * from './tts-rich-text';
+export { default as TtsRichTextEditor } from './tts-rich-text-editor';

package/dist/components/svg-icon/index.d.ts

@@ -0,0 +1,44 @@
+import { App } from 'vue';
+declare const SvgIcon: {
+    new (...args: any[]): import('vue').CreateComponentPublicInstanceWithMixins<Readonly<{
+        prefix?: string;
+        name: string;
+        size?: number | string | Array<number | string>;
+        color?: string;
+    }> & Readonly<{}>, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, import('vue').PublicProps, {
+        prefix: string;
+        size: number | string | Array<number | string>;
+        color: string;
+    }, false, {}, {}, import('vue').GlobalComponents, import('vue').GlobalDirectives, string, {}, HTMLSpanElement, import('vue').ComponentProvideOptions, {
+        P: {};
+        B: {};
+        D: {};
+        C: {};
+        M: {};
+        Defaults: {};
+    }, Readonly<{
+        prefix?: string;
+        name: string;
+        size?: number | string | Array<number | string>;
+        color?: string;
+    }> & Readonly<{}>, {}, {}, {}, {}, {
+        prefix: string;
+        size: number | string | Array<number | string>;
+        color: string;
+    }>;
+    __isFragment?: never;
+    __isTeleport?: never;
+    __isSuspense?: never;
+} & import('vue').ComponentOptionsBase<Readonly<{
+    prefix?: string;
+    name: string;
+    size?: number | string | Array<number | string>;
+    color?: string;
+}> & Readonly<{}>, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, {
+    prefix: string;
+    size: number | string | Array<number | string>;
+    color: string;
+}, {}, string, {}, import('vue').GlobalComponents, import('vue').GlobalDirectives, string, import('vue').ComponentProvideOptions> & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps & {
+    install(app: App): void;
+};
+export default SvgIcon;

package/dist/components/svg-icon/index.vue.d.ts

@@ -0,0 +1,12 @@
+type __VLS_Props = {
+    prefix?: string;
+    name: string;
+    size?: number | string | Array<number | string>;
+    color?: string;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    prefix: string;
+    size: number | string | Array<number | string>;
+    color: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLSpanElement>;
+export default _default;

package/dist/components/tts-rich-text/components/ai-rewrite-modal.vue.d.ts

@@ -0,0 +1,10 @@
+declare const _default: import('vue').DefineComponent<{}, {
+    open: () => void;
+}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    confirm: (text: string) => any;
+}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{
+    onConfirm?: ((text: string) => any) | undefined;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {
+    textBoxRef: HTMLTextAreaElement;
+}, any>;
+export default _default;

package/dist/components/tts-rich-text/components/editor-footer.vue.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, HTMLDivElement>;
+export default _default;

package/dist/components/tts-rich-text/components/editor-tool-button.vue.d.ts

@@ -0,0 +1,67 @@
+import { ToolButtonItem } from './type';
+type __VLS_Props = {
+    item: ToolButtonItem;
+    plain?: boolean;
+    disabled?: boolean;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {
+    getVirtualRef: () => HTMLElement | undefined;
+}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    click: () => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onClick?: (() => any) | undefined;
+}>, {
+    disabled: boolean;
+    plain: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    buttonRef: ({
+        $: import('vue').ComponentInternalInstance;
+        $data: {};
+        $props: {
+            readonly link?: boolean | undefined;
+        } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps;
+        $attrs: import('vue').Attrs;
+        $refs: {
+            [x: string]: unknown;
+        };
+        $slots: Readonly<{
+            [name: string]: import('vue').Slot<any> | undefined;
+        }>;
+        $root: import('vue').ComponentPublicInstance | null;
+        $parent: import('vue').ComponentPublicInstance | null;
+        $host: Element | null;
+        $emit: (event: string, ...args: any[]) => void;
+        $el: any;
+        $options: import('vue').ComponentOptionsBase<Readonly<{
+            link?: boolean;
+        }> & Readonly<{}>, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, {
+            link: boolean;
+        }, {}, string, {}, import('vue').GlobalComponents, import('vue').GlobalDirectives, string, import('vue').ComponentProvideOptions> & {
+            beforeCreate?: (() => void) | (() => void)[];
+            created?: (() => void) | (() => void)[];
+            beforeMount?: (() => void) | (() => void)[];
+            mounted?: (() => void) | (() => void)[];
+            beforeUpdate?: (() => void) | (() => void)[];
+            updated?: (() => void) | (() => void)[];
+            activated?: (() => void) | (() => void)[];
+            deactivated?: (() => void) | (() => void)[];
+            beforeDestroy?: (() => void) | (() => void)[];
+            beforeUnmount?: (() => void) | (() => void)[];
+            destroyed?: (() => void) | (() => void)[];
+            unmounted?: (() => void) | (() => void)[];
+            renderTracked?: ((e: import('vue').DebuggerEvent) => void) | ((e: import('vue').DebuggerEvent) => void)[];
+            renderTriggered?: ((e: import('vue').DebuggerEvent) => void) | ((e: import('vue').DebuggerEvent) => void)[];
+            errorCaptured?: ((err: unknown, instance: import('vue').ComponentPublicInstance | null, info: string) => boolean | void) | ((err: unknown, instance: import('vue').ComponentPublicInstance | null, info: string) => boolean | void)[];
+        };
+        $forceUpdate: () => void;
+        $nextTick: typeof import('vue').nextTick;
+        $watch<T extends string | ((...args: any) => any)>(source: T, cb: T extends (...args: any) => infer R ? (...args: [R, R, import('@vue/reactivity').OnCleanup]) => any : (...args: [any, any, import('@vue/reactivity').OnCleanup]) => any, options?: import('vue').WatchOptions): import('vue').WatchStopHandle;
+    } & Readonly<{
+        link: boolean;
+    }> & Omit<Readonly<{
+        link?: boolean;
+    }> & Readonly<{}>, "link"> & {} & import('vue').ComponentCustomProperties & {} & {
+        $slots: Partial<Record<string, (_: any) => any>>;
+    }) | null;
+}, any>;
+export default _default;