@codady/coax 0.0.3 → 0.0.5

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 AXUI
+Copyright (c) 2026 AXUI
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,236 +1,401 @@
+# Coax - Code Display Web Component
 
-# Coax: A Code Syntax Highlighter for Web Components
+一个优雅的代码高亮和显示 Web 组件。
 
-## Overview
+An elegant code highlighting and display web component.
 
-**Coax** is a custom web component that enables syntax highlighting for various programming languages inside your HTML documents. It allows you to easily embed highlighted code using web standards (Web Components) and modern CSS. This plugin automatically highlights code using regular expressions and supports dynamic theming and customization.
+## 🌟 Features / 功能特性
 
----
-
-## Features
-
-- **Custom Web Component**: Easily use `<ax-code>` to render syntax-highlighted code.
-- **Language Support**: Register custom language configurations for syntax highlighting (e.g., `HTML`, `CSS`, `JavaScript`, `TypeScript`).
-- **Custom Themes**: Add language-specific themes using CSS variables for customization.
-- **Shadow DOM**: Isolated styling and functionality using the Shadow DOM for better encapsulation.
-- **Dynamic CSS**: Dynamically generate styles for each language based on rules.
-
----
-
-## Installation
-
-Simply include the `Coax` JavaScript file in your project, or use the module system if you're using a build tool like Webpack or Rollup.
-
-### Direct inclusion (via script tag)
+- **Syntax Highlighting** - Built-in support for HTML, CSS, JavaScript, TypeScript, Markdown
+- **语法高亮** - 内置 HTML、CSS、JavaScript、TypeScript、Markdown 支持
+- **Typewriter Effect** - Real-time streaming with adjustable speed
+- **打字机效果** - 实时流式显示，速度可调
+- **Dark/Light Mode** - Automatic theme switching based on system preference
+- **明暗模式** - 基于系统偏好自动切换主题
+- **Interactive Tools** - Copy button with visual feedback
+- **交互工具** - 带视觉反馈的复制按钮
+- **Customizable** - Extensive CSS custom properties for styling
+- **高度可定制** - 丰富的 CSS 自定义属性
+- **Line Features** - Line numbers, zebra striping, hover effects
+- **行功能** - 行号、斑马纹、悬停效果
 
-```html
-<script src="path/to/coax.js"></script>
-````
-
----
-
-## Usage
+## 📦 Installation / 安装
 
-To use the Coax code highlighting component, follow these steps:
-
-### 1. Define the `<ax-code>` element
+### CDN Usage / CDN 使用
 
 ```html
-<ax-code lang="js">
-  // Your JavaScript code here
-</ax-code>
-
-<ax-code lang="css">
-  /* Your CSS code here */
-</ax-code>
+<!-- 直接引入 UMD 版本 -->
+<script src="https://unpkg.com/@codady/coax@latest"></script>
 
-<ax-code lang="html">
-  <!-- Your HTML code here -->
-</ax-code>
+<!-- 或者使用模块化方式 -->
+<script type="module">
+  import 'https://unpkg.com/@codady/coax@latest';
+</script>
 ```
 
-### 2. Register Language Configurations
+### NPM Installation / NPM 安装
 
-You can register languages with their syntax rules and themes using the `Coax.register` method.
+```bash
+npm install @codady/coax
+# 或者
+yarn add @codady/coax
+```
 
 ```javascript
-Coax.register('html', {
-  rules: [
-    { name: 'comment', reg: /&lt;!--[\s\S]*?--&gt;/ },
-    { name: 'tag', reg: /&lt;\/?[a-zA-Z0-9]+/ },
-    { name: 'attr', reg: /[a-zA-Z-]+(?=\s*=\s*)/ },
-    { name: 'string', reg: /(['"])(?:\\.|[^\\])*?\1/ },
-  ],
-  theme: {
-    'tag': '#e06c75', // red
-    'attr': '#d19a66', // orange
-    'string': '#98c379', // green
-  }
-});
+// 在您的模块中导入
+import '@codady/coax';
 ```
 
-### 3. Customization
+## 🚀 Quick Start / 快速开始
 
-You can customize the code highlighting by modifying the language's rules, theme colors, or internal CSS using the `theme`, `internalCss`, and `cssPrefix` properties.
+### Basic Usage / 基本使用
 
-Example:
-
-```javascript
-Coax.register('css', {
-  rules: [
-    { name: 'comment', reg: /\/\*[\s\S]*?\*\// },
-    { name: 'property', reg: /[a-z-]+(?=\s*:)/ },
-    { name: 'selector', reg: /[.#a-z0-9, \n\t>:+()_-]+(?=\s*\{)/i },
-    { name: 'unit', reg: /(?<=\d)(px|em|rem|%|vh|vw|ms|s|deg)/ },
-  ],
-  theme: {
-    'keyword': '#61afef', // blue
-    'string': '#98c379', // green
-    'op': '#abb2bf', // gray
-  },
-  internalCss: `
-    .ax-css-string { color: var(--ax-code-string); }
-  `
-});
+```html
+<!-- 注册组件后使用 -->
+<ax-code lang="js">
+function greet(name) {
+    console.log(`Hello, ${name}!`);
+    return true;
+}
+</ax-code>
 ```
 
-### 4. Optional Attributes
-
-You can customize the code block's height and max height:
+### All Features / 全部功能
 
 ```html
-<ax-code lang="js" height="200px" max-height="400px">
-  const x = 10;
+<ax-code 
+    lang="ts" 
+    speed="5"
+    indexed
+    striped
+    hoverable
+    wrapped
+    scheme="dark"
+    tools="copy"
+    height="300px"
+    max-height="500px"
+>
+interface User {
+    id: number;
+    name: string;
+    email: string;
+    
+    greet(): string;
+}
+
+const user: User = {
+    id: 1,
+    name: "John",
+    email: "john@example.com",
+    greet() {
+        return `Hello, ${this.name}!`;
+    }
+};
 </ax-code>
 ```
 
----
+## 📚 API Reference / API 参考
 
-## Development
+### Attributes / 属性
 
-If you'd like to extend or modify the plugin, the source code is available for you to contribute or adapt.
+| Attribute | Type | Default | Description | 描述 |
+|-----------|------|---------|-------------|------|
+| `lang` | string | `'plain'` | Programming language | 编程语言 |
+| `speed` | number | `5` | Typing speed (higher = slower) | 打字速度（值越高越慢） |
+| `indexed` | boolean | `false` | Show line numbers | 显示行号 |
+| `striped` | boolean | `false` | Zebra striping | 斑马纹背景 |
+| `hoverable` | boolean | `false` | Highlight line on hover | 鼠标悬停高亮 |
+| `wrapped` | boolean | `false` | Line wrapping | 自动换行 |
+| `unnamed` | boolean | `false` | Hide language name | 隐藏语言名称 |
+| `sanitized` | boolean | `false` | Remove empty lines | 移除空行 |
+| `scheme` | string | `'auto'` | Color scheme: `light`, `dark`, `auto` | 配色方案 |
+| `height` | string | `'auto'` | Container height | 容器高度 |
+| `max-height` | string | `'500px'` | Max container height | 最大容器高度 |
+| `tools` | string | `''` | Comma-separated tools | 逗号分隔的工具 |
 
-* **Clone the repository**: `git clone https://github.com/your-repository`
-* **Run build tools** (e.g., Webpack, Babel) for production optimization.
+### Supported Languages / 支持的语言
 
----
+| Language | Alias | Key |
+|----------|-------|-----|
+| JavaScript | Javascript | `js` |
+| TypeScript | Typescript | `ts` |
+| HTML | HTML | `html` |
+| CSS | CSS | `css` |
+| Markdown | Markdown | `md` |
+| Plain Text | Plain Text | `plain` |
 
-## License
+### Methods / 方法
 
-MIT License. Feel free to use and modify it for your projects.
+#### Static Methods / 静态方法
 
----
+```javascript
+// Register a new language
+Coax.register('python', {
+    alias: 'Python',
+    rules: [
+        { token: 'keyword', pattern: /\b(def|class|if|else|for|while)\b/, light: '#d73a49', dark: '#ff7b72' },
+        // ... more rules
+    ]
+});
 
-# 中文文档
+// Register custom tools
+Coax.addTools([
+    {
+        name: 'download',
+        icon: '<svg>...</svg>',
+        action: function() {
+            // Download code as file
+        }
+    }
+]);
+```
 
-## 概述
+#### Instance Methods / 实例方法
 
-**Coax** 是一个自定义 Web 组件，可以在 HTML 文档中嵌入高亮的代码。它允许您使用现代 Web 标准（Web 组件）和 CSS 来轻松实现代码高亮。该插件通过正则表达式自动高亮代码，并支持动态主题和自定义设置。
+```javascript
+const codeElement = document.querySelector('ax-code');
 
----
+// Replace all code
+codeElement.replace('const x = 10;');
 
-## 特性
+// Append new code
+codeElement.append('\nconsole.log(x);');
 
-* **自定义 Web 组件**：使用 `<ax-code>` 标签轻松渲染代码高亮。
-* **语言支持**：为每种编程语言注册自定义语法高亮配置（例如，`HTML`，`CSS`，`JavaScript`，`TypeScript`）。
-* **自定义主题**：使用 CSS 变量添加语言特定的主题，支持个性化定制。
-* **Shadow DOM**：使用 Shadow DOM 实现样式和功能的隔离。
-* **动态 CSS**：基于规则动态生成每种语言的样式。
+// Stream code with typewriter effect
+codeElement.stream('function test() {\n', true);
 
----
+// Clear all code
+codeElement.clear();
 
-## 安装
+// Get current source
+console.log(codeElement.source);
 
-只需将 `Coax` 的 JavaScript 文件包含到您的项目中，或使用构建工具（如 Webpack 或 Rollup）进行模块化引入。
+// Control auto-scroll
+codeElement.autoScroll = false;
+```
 
-### 直接引入（通过 `<script>` 标签）
+## 🎨 Customization / 自定义
+
+### CSS Custom Properties / CSS 自定义属性
+
+```css
+/* 全局样式覆盖 */
+ax-code {
+    /* 布局 */
+    --ax-code-font-size: 14px;
+    --ax-code-line-height: 1.6;
+    --ax-code-padding: 1rem;
+    --ax-code-radius: 8px;
+
+    /* 语言特定颜色 */
+    --ax-js-keyword: #d73a49;
+    --ax-js-string: #032f62;
+    
+    /* 亮色主题 */
+    --ax-code-background-color: #f8f9fa;
+    --ax-code-color: #212529;
+    --ax-code-border-color: #dee2e6;
+
+}
+ax-code[scheme]{
+    /* 暗色主题 */
+    --ax-code-dark-background: #1a1d23;
+    --ax-code-dark-color: #e9ecef;
+    --ax-code-dark-border: #495057;
+}
 
-```html
-<script src="path/to/coax.js"></script>
 ```
 
----
+### Register Custom Language / 注册自定义语言
 
-## 使用方法
+```javascript
+// 定义新的语言规则
+const pythonRules = [
+    {
+        token: 'keyword',
+        pattern: /\b(def|class|if|elif|else|for|while|try|except|finally|with|import|from|as)\b/,
+        light: '#d73a49',
+        dark: '#ff7b72'
+    },
+    {
+        token: 'string',
+        pattern: /(['"`])(?:\\.|[^\\'"\b])*?(?:['"`])/,
+        light: '#032f62',
+        dark: '#98c379'
+    },
+    {
+        token: 'comment',
+        pattern: /#.*/,
+        light: '#6a737d',
+        dark: '#8b949e'
+    },
+    {
+        token: 'decorator',
+        pattern: /@\w+/,
+        light: '#6f42c1',
+        dark: '#d2a8ff'
+    }
+];
+
+// 注册到 Coax
+Coax.register('python', {
+    alias: 'Python 3',
+    rules: pythonRules,
+    themeStyles: `
+        /* 额外样式 */
+        .ax-python-decorator {
+            font-style: italic;
+        }
+    `
+});
+```
 
-要使用 Coax 代码高亮组件，请按照以下步骤进行操作：
+### Create Custom Tools / 创建自定义工具
 
-### 1. 定义 `<ax-code>` 元素
+```javascript
+// 创建格式化工具
+const formatTool = {
+    name: 'format',
+    icon: `<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor">
+        <polygon points="3 11 22 2 13 21 11 13 3 11"></polygon>
+    </svg>`,
+    title: 'Format Code',
+    action: function() {
+        // 使用 Prettier 或其他格式化工具
+        const formatted = prettier.format(this.source, {
+            parser: 'babel',
+            semi: true,
+            singleQuote: true
+        });
+        this.replace(formatted);
+    }
+};
+
+// 创建分享工具
+const shareTool = {
+    name: 'share',
+    icon: `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor">
+        <path d="M4 12v8a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-8"></path>
+        <polyline points="16 6 12 2 8 6"></polyline><line x1="12" y1="2" x2="12" y2="15"></line>
+    </svg>`,
+    title: 'Share Code',
+    action: function() {
+        // 创建分享链接
+        const code = encodeURIComponent(this.source);
+        const url = `${window.location.origin}/share?code=${code}`;
+        navigator.clipboard.writeText(url);
+        alert('Share link copied to clipboard!');
+    }
+};
+
+// 注册工具
+Coax.addTools([formatTool, shareTool]);
+```
 
-```html
-<ax-code lang="js">
-  // 这里是您的 JavaScript 代码
-</ax-code>
+## 📝 Examples / 示例
 
-<ax-code lang="css">
-  /* 这里是您的 CSS 代码 */
-</ax-code>
+### Interactive Demo / 交互式演示
 
-<ax-code lang="html">
-  <!-- 这里是您的 HTML 代码 -->
-</ax-code>
+```html
+<!DOCTYPE html>
+<html>
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Coax</title>
+    <style>
+    </style>
+
+</head>
+
+<body>
+    <ax-code streaming tools="copy" indexed lang="js">
+        <code>
+/**
+ * Simple animation function
+ */
+async function animate(element, duration) {
+    const start = Date.now();
+    
+    if (!element) return false;
+
+    console.log("Animation started...");
+
+    while (Date.now() - start < duration) {
+        let progress = (Date.now() - start) / duration;
+        element.style.opacity = Math.min(progress, 1);
+        await Promise.resolve();
+    }
+    
+    return true;
+}
+        </code>
+    </ax-code>
+
+    <script src="https://unpkg.com/@codady/coax@latest/dist/coax.umd.js" type='text/javascript'></script>
+</body>
+
+</html>
 ```
 
-### 2. 注册语言配置
-
-您可以使用 `Coax.register` 方法注册语言的语法规则和主题。
+### Advanced Usage / 高级用法
 
 ```javascript
-Coax.register('html', {
-  rules: [
-    { name: 'comment', reg: /&lt;!--[\s\S]*?--&gt;/ },
-    { name: 'tag', reg: /&lt;\/?[a-zA-Z0-9]+/ },
-    { name: 'attr', reg: /[a-zA-Z-]+(?=\s*=\s*)/ },
-    { name: 'string', reg: /(['"])(?:\\.|[^\\])*?\1/ },
-  ],
-  theme: {
-    'tag': '#e06c75', // 红色
-    'attr': '#d19a66', // 橙色
-    'string': '#98c379', // 绿色
-  }
+// 动态创建代码块
+const createCodeBlock = (lang, code) => {
+    const codeBlock = document.createElement('ax-code');
+    codeBlock.setAttribute('lang', lang);
+    codeBlock.textContent = code;
+    return codeBlock;
+};
+
+// 添加到页面
+document.body.appendChild(createCodeBlock('js', 'const x = 10;'));
+
+// 响应式监听
+const codeElement = document.querySelector('ax-code');
+const observer = new MutationObserver((mutations) => {
+    mutations.forEach((mutation) => {
+        if (mutation.attributeName === 'lang') {
+            console.log('Language changed to:', codeElement.lang);
+        }
+    });
 });
-```
 
-### 3. 自定义设置
+observer.observe(codeElement, { attributes: true });
 
-您可以通过修改语言的规则、主题颜色或内部 CSS 来定制代码高亮，具体方法如下：
-
-```javascript
-Coax.register('css', {
-  rules: [
-    { name: 'comment', reg: /\/\*[\s\S]*?\*\// },
-    { name: 'property', reg: /[a-z-]+(?=\s*:)/ },
-    { name: 'selector', reg: /[.#a-z0-9, \n\t>:+()_-]+(?=\s*\{)/i },
-    { name: 'unit', reg: /(?<=\d)(px|em|rem|%|vh|vw|ms|s|deg)/ },
-  ],
-  theme: {
-    'keyword': '#61afef', // 蓝色
-    'string': '#98c379', // 绿色
-    'op': '#abb2bf', // 灰色
-  },
-  internalCss: `
-    .ax-css-string { color: var(--ax-code-string); }
-  `
+// 键盘快捷键
+document.addEventListener('keydown', (e) => {
+    if (e.ctrlKey && e.key === 'c' && document.activeElement === codeElement) {
+        e.preventDefault();
+        navigator.clipboard.writeText(codeElement.source);
+    }
 });
 ```
 
-### 4. 可选属性
 
-您可以通过 `height` 和 `max-height` 属性自定义代码块的高度和最大高度：
+## 📄 License / 许可证
 
-```html
-<ax-code lang="js" height="200px" max-height="400px">
-  const x = 10;
-</ax-code>
-```
+MIT License. See LICENSE file for details.
 
----
+This software supports the MIT License, allowing free learning and commercial use, but please retain the terms 'coax', 'Coax' and 'COAX' within the software.
 
-## 许可证
+MIT 许可证。详见 LICENSE 文件。
 
-MIT 许可证。可以自由使用和修改代码以适应您的项目需求。
+本软件支持 MIT 许可证，允许自由学习和商业使用，但请保留软件中的 'coax'、'Coax' 和 'COAX' 字样。
 
-```
+
+### Contact / 联系
+
+- **Email**: 3217728223@qq.com
+- **Author**: AXUI development team
 
 ---
 
+**Made with ❤️ by the AXUI Development Team**
+
+**由 AXUI 开发团队用心打造**
+
+> "Elegant code deserves elegant display."  
+> "优雅的代码值得优雅的展示。"