@chenyomi/leafer-htmltext-edit 2.2.3 → 2.2.4

package/README.md

@@ -9,7 +9,7 @@
 
 一个强大的 Leafer UI 富文本编辑器插件，集成 Quill 2.0，支持 HTML 文本编辑和丰富的文本样式控制。
 
-[English](./README_EN.md)
+[English Document](./README_EN.md)
 
 ## ✨ 特性
 

package/README_EN.md

@@ -0,0 +1,618 @@
+# Leafer HTMLText Editor
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/@chenyomi/leafer-htmltext-edit.svg" alt="npm version">
+  <img src="https://img.shields.io/npm/dm/@chenyomi/leafer-htmltext-edit.svg" alt="npm downloads">
+  <img src="https://img.shields.io/npm/l/@chenyomi/leafer-htmltext-edit.svg" alt="license">
+  <img src="https://img.shields.io/badge/TypeScript-Ready-blue.svg" alt="TypeScript">
+</p>
+
+A powerful rich text editor plugin for Leafer UI, integrated with Quill 2.0, supporting HTML text editing and comprehensive text styling controls.
+
+[中文文档](./README.md)
+
+## ✨ Features
+
+- 🎨 **Rich Text Editing** - Based on Quill 2.0, supports full rich text editing capabilities
+- 🔤 **Multi-language Fonts** - Supports custom fonts
+- 📐 **Text Styling** - Comprehensive control over font, size, color, alignment, line height, letter spacing, and more
+- 📝 **Formatting Tools** - Bold, italic, underline, strikethrough, superscript, subscript
+- 📋 **List Support** - Ordered and unordered lists
+- 🎯 **Perfect Integration** - Seamlessly integrates into the Leafer UI ecosystem
+- 🔐 **License Management** - Built-in licensing system, no restrictions for local development, requires license for production
+- 📦 **Lightweight** - Minified and obfuscated code, small size, fast loading
+- 🔧 **TypeScript** - Full type definition support
+- 🚀 **Modern Build** - ESM + CJS dual format, supports Tree Shaking
+
+- [Official Website](https://chenyomi.github.io/leafer-htmltext-edit-website/)
+- [Live Demo](https://chenyomi.github.io/leafer-htmltext-edit-view/)
+- [Issue Tracker](https://github.com/chenyomi/leafer-htmltext-edit-view/issues)
+
+## 📦 Installation
+
+```bash
+npm install @chenyomi/leafer-htmltext-edit
+```
+
+Or using other package managers:
+
+```bash
+# pnpm
+pnpm add @chenyomi/leafer-htmltext-edit
+
+# yarn
+yarn add @chenyomi/leafer-htmltext-edit
+```
+
+### Peer Dependencies
+
+This plugin requires the following dependencies (please ensure they are installed):
+
+```bash
+npm install leafer-ui @leafer-ui/core @leafer-in/editor @leafer-in/html quill
+```
+
+## 🚀 Quick Start
+
+### Vite Project Configuration
+
+To ensure the plugin works properly, it's recommended to add the following settings to your Vite configuration:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  resolve: {
+    // Ensure using project's dependency instances
+    dedupe: [
+      "@leafer-ui/core",
+      "@leafer-in/editor",
+      "@leafer-in/html",
+      "leafer-ui",
+      "quill",
+    ],
+  },
+  optimizeDeps: {
+    // Exclude plugin from pre-bundling
+    exclude: ["@chenyomi/leafer-htmltext-edit"],
+  },
+});
+```
+
+### Webpack Project Configuration
+
+```javascript
+// webpack.config.js
+module.exports = {
+  resolve: {
+    // Ensure single instance usage
+    alias: {
+      quill: require.resolve("quill"),
+      "@leafer-ui/core": require.resolve("@leafer-ui/core"),
+      "@leafer-in/editor": require.resolve("@leafer-in/editor"),
+      "@leafer-in/html": require.resolve("@leafer-in/html"),
+      "leafer-ui": require.resolve("leafer-ui"),
+    },
+  },
+};
+```
+
+### Using in Vue 3
+
+```vue
+<template>
+  <div id="leafer-view" style="width: 100vw; height: 100vh;"></div>
+</template>
+
+<script setup lang="ts">
+import { onMounted } from "vue";
+import { App } from "leafer-ui";
+import "leafer-editor";
+import {
+  htmlTextManage,
+  setLicense,
+  setHTMLText,
+  HtmlText,
+} from "@chenyomi/leafer-htmltext-edit";
+
+onMounted(async () => {
+  // 1. Set License (must be done before init)
+  const licenseKey = "Contact author for license";
+  const success = await setLicense(licenseKey);
+
+  if (!success) {
+    console.error("License validation failed");
+    // You can display an error message to the user
+  }
+
+  const leafer = new App({
+    view: "leafer-view",
+    fill: "#ffffff",
+    editor: {},
+  });
+
+  htmlTextManage.init(leafer);
+
+  let { width = 1200, height = 960 } = leafer;
+  const text_ = new HtmlText({
+    editOuter: "TextEditTool",
+    name: "Text",
+    x: width / 2 - 100,
+    y: height * 0.4,
+    editable: true,
+    draggable: true,
+    fontFamily: undefined,
+    fontSize: 30,
+    lineHeight: 1.5,
+    letterSpacing: 0,
+    textShadow: undefined,
+    alignContent: "start",
+  });
+
+  leafer.tree.add([text_]);
+});
+</script>
+```
+
+### Using in React
+
+```tsx
+// Refer to Vue 3 example - similar implementation
+```
+
+### Using in Angular
+
+```typescript
+// Refer to Vue 3 example - similar implementation
+```
+
+## 📚 API Documentation
+
+### HtmlTextManage
+
+Singleton editor manager responsible for managing Quill instances and text editing.
+
+#### Static Methods
+
+##### `init(app: any): Promise<Quill>`
+
+Initialize Quill editor and bind to Leafer application.
+
+```typescript
+const quill = await HtmlTextManage.init(app);
+```
+
+**Parameters:**
+
+- `app` - Leafer App instance
+
+**Returns:** Promise<Quill> - Quill editor instance
+
+##### `getQuill(): Quill`
+
+Get the Quill instance.
+
+```typescript
+const quill = HtmlTextManage.getQuill();
+```
+
+**Returns:** Quill - Quill editor instance
+
+##### `getCanvas(): any`
+
+Get the Leafer App instance.
+
+```typescript
+const app = HtmlTextManage.getCanvas();
+```
+
+**Returns:** App - Leafer application instance
+
+##### `isMultiSelect(): boolean`
+
+Check if multiple objects are selected.
+
+```typescript
+if (HtmlTextManage.isMultiSelect()) {
+  console.log("Multiple objects selected");
+}
+```
+
+**Returns:** boolean - Whether multiple objects are selected
+
+##### `dateEdit(callback: (leaf: any) => void, level?: number, listNew?: any): void`
+
+Batch edit selected objects.
+
+```typescript
+HtmlTextManage.dateEdit((leaf) => {
+  leaf.fontSize = 20;
+  leaf.fill = "#ff0000";
+});
+```
+
+**Parameters:**
+
+- `callback` - Edit callback function, receives each selected object
+- `level?` - Optional, edit level
+- `listNew?` - Optional, new object list
+
+### License Management
+
+The plugin has a built-in licensing system for commercial use.
+
+#### `setLicense(licenseKey: string): boolean`
+
+Set the license key.
+
+```typescript
+import { setLicense } from "@chenyomi/leafer-htmltext-edit";
+
+const success = setLicense("your-license-key");
+if (success) {
+  console.log("License activated successfully");
+}
+```
+
+**Parameters:**
+
+- `licenseKey` - License key string
+
+**Returns:** boolean - Whether activation was successful
+
+#### `checkLicense(): boolean`
+
+Check license status.
+
+```typescript
+import { checkLicense } from "@chenyomi/leafer-htmltext-edit";
+
+if (checkLicense()) {
+  console.log("License is valid");
+} else {
+  console.log("License is invalid or expired");
+}
+```
+
+### HtmlText
+
+Custom HTML text class, extends Leafer's text object.
+
+```typescript
+import { HtmlText } from "@chenyomi/leafer-htmltext-edit";
+
+// HtmlText is automatically registered in Leafer
+// Can be used directly in Leafer
+```
+
+### Utility Functions
+
+#### `updataHtmlText(obj: any): void`
+
+Update HTML text object.
+
+```typescript
+import { updataHtmlText } from "@chenyomi/leafer-htmltext-edit";
+
+updataHtmlText(textObject);
+```
+
+#### `setHTMLText(type: string, value: any, inner: any, editor: any, multi: boolean): void`
+
+Set HTML text properties.
+
+```typescript
+import { setHTMLText } from "@chenyomi/leafer-htmltext-edit";
+
+// Set font size
+setHTMLText("fontSize", 24, null, editor, false);
+```
+
+## 🎨 Usage Examples
+
+### Setting Text Styles
+
+```typescript
+import { setHTMLText } from "@chenyomi/leafer-htmltext-edit";
+```
+
+```html
+<button @click="setHTMLText('bold')">Bold</button>
+<button @click="setHTMLText('italic')">Italic</button>
+<button @click="setHTMLText('underline')">Underline</button>
+<button @click="setHTMLText('strike')">Strikethrough</button>
+<button @click="setHTMLText('textCase')">Text Case</button>
+<button @click="setHTMLText('script', 'super')">Superscript</button>
+<button @click="setHTMLText('script', 'sub')">Subscript</button>
+<button @click="setHTMLText('align', false)">Align Left</button>
+<button @click="setHTMLText('align', 'center')">Align Center</button>
+<button @click="setHTMLText('align', 'right')">Align Right</button>
+<button @click="setHTMLText('alignContent', 'start')">Align Top</button>
+<button @click="setHTMLText('alignContent', 'center')">Align Middle</button>
+<button @click="setHTMLText('alignContent', 'end')">Align Bottom</button>
+<button @click="setHTMLText('list', 'ordered')">Ordered List</button>
+<button @click="setHTMLText('list', 'bullet')">Bullet List</button>
+<button @click="setHTMLText('color', '#3CB72C')">#3CB72C</button>
+<button @click="setHTMLText('color', '#000000')">#000000</button>
+<button @click="setHTMLText('lineHeight', 1.5)">Line Height 1.5</button>
+<button @click="setHTMLText('lineHeight', 3)">Line Height 3.0</button>
+<button @click="setHTMLText('letterSpacing', 0)">Letter Spacing 0</button>
+<button @click="setHTMLText('letterSpacing', 3)">Letter Spacing 3</button>
+<button @click="setHTMLText('textShadow', '3px 3px 3px rgba(0, 0, 0, 0.5)')">
+  Shadow
+</button>
+<button @click="setHTMLText('textShadow', undefined)">No Shadow</button>
+<button @click="changeFontFamily">Font Family</button>
+<button @click="setHTMLText('fontSize', 100)">Large Font</button>
+<button @click="reload">Reset</button>
+```
+
+### Batch Editing Multiple Objects
+
+```typescript
+// When multiple text objects are selected
+if (HtmlTextManage.isMultiSelect()) {
+  HtmlTextManage.dateEdit((leaf) => {
+    leaf.fontSize = 18;
+    leaf.fontFamily = "Inter";
+    leaf.fill = "#333333";
+    leaf.textAlign = "center";
+  });
+}
+```
+
+### Listening to Text Changes
+
+```typescript
+const quill = HtmlTextManage.getQuill();
+
+// Listen to text content changes
+quill.on("text-change", (delta, oldDelta, source) => {
+  console.log("Text changed:", delta);
+  console.log("Source:", source); // 'user' or 'api'
+});
+
+// Listen to selection changes
+quill.on("selection-change", (range, oldRange, source) => {
+  if (range) {
+    console.log("Selection:", range.index, range.length);
+  } else {
+    console.log("Editor lost focus");
+  }
+});
+
+// Listen to editor changes
+quill.on("editor-change", (eventName, ...args) => {
+  console.log("Editor event:", eventName);
+});
+```
+
+### Formatting Text
+
+```typescript
+const quill = HtmlTextManage.getQuill();
+
+// Bold
+quill.format("bold", true);
+
+// Italic
+quill.format("italic", true);
+
+// Underline
+quill.format("underline", true);
+
+// Strikethrough
+quill.format("strike", true);
+
+// Superscript
+quill.format("script", "super");
+
+// Subscript
+quill.format("script", "sub");
+
+// Lists
+quill.format("list", "ordered"); // Ordered list
+quill.format("list", "bullet"); // Bullet list
+```
+
+### Inserting Content
+
+```typescript
+const quill = HtmlTextManage.getQuill();
+
+// Insert text
+quill.insertText(0, "Hello World!");
+
+// Insert formatted text
+quill.insertText(0, "Hello", { bold: true, color: "red" });
+
+// Get text content
+const text = quill.getText();
+
+// Get HTML content
+const html = quill.root.innerHTML;
+
+// Set content
+quill.setContents([
+  { insert: "Hello " },
+  { insert: "World", attributes: { bold: true } },
+  { insert: "\n" },
+]);
+```
+
+## 🔤 Supported Fonts
+
+### Custom Fonts (IMPORTANT‼️)
+
+### The editor consists of internal and external editors
+
+### Internal editor fonts must be loaded in the current project
+
+### External editor fonts must be passed as base64 for displaying HTML converted to SVG with embedded fonts
+
+```typescript
+import { HtmlTextManage } from "@chenyomi/leafer-htmltext-edit";
+
+// Get Quill instance
+const quill = HtmlTextManage.getQuill();
+
+const fontFamily = '"Dancing Script", cursive';
+const fontBase64 = "base64-encoded font data";
+setHTMLText("font", fontFamily, fontBase64);
+```
+
+### TypeScript Configuration
+
+Ensure your `tsconfig.json` includes the correct type definitions:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  }
+}
+```
+
+## 🔧 Development
+
+### Clone Repository
+
+```bash
+git clone https://github.com/chenyomi/leafer-htmltext-edit.git
+cd leafer-htmltext-edit
+```
+
+### Install Dependencies
+
+```bash
+npm install
+```
+
+### Build
+
+```bash
+# Production build (minified and obfuscated)
+npm run build
+```
+
+## 📝 FAQ
+
+### Q: How to import CSS styles?
+
+A: The plugin's CSS is automatically injected, no manual import needed. If you encounter style issues, you can manually import Quill CSS:
+
+```typescript
+import "quill/dist/quill.core.css";
+```
+
+### Q: Why isn't the editor showing?
+
+A: Please ensure:
+
+1. All peer dependencies are correctly installed
+2. Called `HtmlTextManage.init(app)` and waited for Promise completion
+3. Created an `Editor` instance
+4. Added `dedupe` or `alias` settings in Vite/Webpack configuration
+5. Check browser console for error messages
+
+### Q: Which browsers are supported?
+
+A: Supports all modern browsers:
+
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
+
+IE11 and earlier versions are not supported.
+
+### Q: How to obtain a license?
+
+A: Please contact the developer for a commercial license key:
+
+- Email: 408550179@qq.com
+- TG: [https://t.me/Ccymmm](https://t.me/Ccymmm)
+
+### Q: How to optimize performance?
+
+A: Best practices:
+
+1. Use `build:watch` mode for development to avoid frequent rebuilds
+2. Load large documents in segments
+3. Avoid frequent calls to `dateEdit` in short periods
+4. Use debounce for high-frequency events
+
+### Q: How to handle Chinese input method issues?
+
+A: Quill 2.0 has built-in support for Chinese input methods. If you encounter issues:
+
+```typescript
+const quill = HtmlTextManage.getQuill();
+
+// Listen to composition events
+quill.keyboard.addBinding({
+  key: "Enter",
+  handler: function (range, context) {
+    // Custom handling logic
+  },
+});
+```
+
+## 🤝 Contributing
+
+Issues and Pull Requests are welcome!
+
+### Contribution Guidelines
+
+1. Fork this repository
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+### Development Standards
+
+- Follow TypeScript best practices
+- Add necessary type definitions
+- Write clear comments
+- Update relevant documentation
+- Ensure all tests pass
+
+## 📄 License
+
+This project is licensed under the [MIT](./LICENSE) License.
+
+### Commercial Use
+
+This plugin supports commercial use but requires a license key. Please contact the developer for authorization.
+
+## 👤 Author
+
+**chenyomi**
+
+- npm: [@chenyomi](https://www.npmjs.com/~chenyomi)
+- Email: 408550179@qq.com
+- TG: [https://t.me/Ccymmm](https://t.me/Ccymmm)
+
+## 🙏 Acknowledgments
+
+- [Leafer UI](https://www.leaferjs.com/) - Powerful Canvas rendering engine
+- [Quill](https://quilljs.com/) - Modern rich text editor
+- [TypeScript](https://www.typescriptlang.org/) - JavaScript superset
+- [Google Fonts](https://fonts.google.com/) - Quality open-source fonts
+
+## 📊 Stats
+
+![npm version](https://img.shields.io/npm/v/@chenyomi/leafer-htmltext-edit)
+![npm downloads](https://img.shields.io/npm/dt/@chenyomi/leafer-htmltext-edit)
+![bundle size](https://img.shields.io/bundlephobia/minzip/@chenyomi/leafer-htmltext-edit)
+![license](https://img.shields.io/npm/l/@chenyomi/leafer-htmltext-edit)
+![stars](https://img.shields.io/github/stars/chenyomi/leafer-htmltext-edit)
+
+---
+
+If this project helps you, please give it a ⭐️ Star! Your support is our greatest motivation!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chenyomi/leafer-htmltext-edit",
-  "version": "2.2.3",
+  "version": "2.2.4",
   "description": "A text editor plugin for Leafer UI with HTML text support",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -57,6 +57,7 @@
   "files": [
     "dist",
     "README.md",
+    "README_EN.md",
     "LICENSE"
   ],
   "publishConfig": {