@codady/coax 0.0.3 → 0.0.5

package/src/components/{CoaxElem.ts → Coax.ts}

@@ -1,10 +1,9 @@
 /**
- *  Last modified: 2026/01/12 09:40:20
+ *  Last modified: 2026/01/12 15:11:21
+ * Coax - A custom web component for syntax highlighting, code display, and interactive features
+ * 
  */
 
-
-import icaxCopy from "@codady/icax/src/icaxCopy";
-import icaxCheck from "@codady/icax/src/icaxCheck";
 import typeWriter from "@codady/utils/typeWriter";
 import parseClasses from "@codady/utils/parseClasses";
 import NAMESPACE from "@codady/utils/namespace";
@@ -15,37 +14,44 @@ import createEl from "@codady/utils/createEl";
 
 // Define the structure for the language configuration
 export interface LanguageRule {
-    token: string;
-    pattern: RegExp;
-    light?: string;
-    dark?: string;
+    token: string;        // Token representing a specific syntax element (e.g., keyword, string, comment)
+    pattern: RegExp;      // Regular expression used to match the syntax element
+    light?: string;       // Optional CSS color for light mode
+    dark?: string;        // Optional CSS color for dark mode
 }
 
 export interface LanguageConfig {
     rules: LanguageRule[];  // Array of syntax highlighting rules
-    alias?: string;         // Alias name
+    alias?: string;         // Alias name for the language (e.g., 'JavaScript', 'JS', etc.)
     themeStyles?: string;   // Optional internal CSS for language-specific styles
-    cssPrefix?: string;     // Optional CSS prefix for class names
+    cssPrefix?: string;     // Optional CSS prefix for class names used in syntax highlighting
 }
 
-class CoaxElem extends HTMLElement {
+class Coax extends HTMLElement {
     // A static Map to hold the configuration for different languages
     static languages = new Map<string, LanguageConfig>();
+
+    // A static array to hold the tools registered with the component
     static tools: any[] = [];
-    private source: string;
-    private _renderQueued = false;
-    private baseStylesEl!: HTMLStyleElement;
-    private themeStylesEl!: HTMLStyleElement;
-    private dynamicStylesEl!: HTMLStyleElement;
-    private highlightedCodeEl!: HTMLElement;
-    private headerEl!: HTMLElement;
-    private codeNameEl!: HTMLElement;
-    private codeToolsEl!: HTMLElement;
-    private codeBodyEl!: HTMLElement;
-    public alias: string;
-    public lineString: string;
-    public speed: number;
-    public autoScroll: boolean;
+
+    private source: string;  // Source code content to be highlighted
+    private _renderQueued = false;  // Flag to prevent multiple render requests
+    private baseStylesEl!: HTMLStyleElement;  // Element for base styles
+    private themeStylesEl!: HTMLStyleElement;  // Element for theme styles
+    private dynamicStylesEl!: HTMLStyleElement;  // Element for dynamic styles
+    private highlightEl!: HTMLElement;  // Element that holds the highlighted code
+    private headerEl!: HTMLElement;  // Header element (for code name, tools, etc.)
+    private codeNameEl!: HTMLElement;  // Code name element (shows language or alias)
+    private codeToolsEl!: HTMLElement;  // Code tools element (for interactive tools like copy)
+    private codeBodyEl!: HTMLElement;  // Code body element (the container for the code)
+
+    public lang: string = 'plain';  // Language of the code (default is plain text)
+    public alias: string = 'Plain Text';  // Alias name for the language (default is 'Plain Text')
+    public lineString: string = '';  // The current line's string being typed
+    public lastLineString: string = '';  // The last line's string
+    public speed: number = 5;  // Speed of the typing effect (higher is slower)
+    public autoScroll: boolean = true;  // Flag to enable/disable auto-scrolling
+    public canListen: boolean = true;  // Flag to enable/disable auto-scrolling
 
     constructor() {
         super();
@@ -53,12 +59,7 @@ class CoaxElem extends HTMLElement {
         this.attachShadow({ mode: 'open' });
         // Remove leading/trailing whitespace from the raw code content
         this.source = this.textContent?.replace(/^\s*\n|\n\s*$/g, '') || '';
-        this.lang = 'plain';
-        this.alias = 'Plain Text';
-        this.lineString = '';
-        this.speed = 5;
-        this.autoScroll = true;
-        // 1. 初始化基础骨架
+        // Initialize the basic structure of the component
         (this.shadowRoot as any).innerHTML = `
             <style id="base-styles">
                 :host { 
@@ -188,11 +189,11 @@ class CoaxElem extends HTMLElement {
             <style id="theme-styles"></style>
             <div id="code-header"><span id="code-name">${this.alias}</span><div id="code-tools"></div></div>
             <div id="code-body">
-                <pre><code id="highlight-code"></code></pre>
+                <pre><code id="highlight"></code></pre>
             </div>
         `;
 
-        // 缓存引用
+        // Cache references to various elements
         this.baseStylesEl = getEl('#base-styles', this.shadowRoot) as HTMLStyleElement;
         this.themeStylesEl = getEl('#theme-styles', this.shadowRoot) as HTMLStyleElement;
         this.dynamicStylesEl = getEl('#dynamic-styles', this.shadowRoot) as HTMLStyleElement;
@@ -200,28 +201,34 @@ class CoaxElem extends HTMLElement {
         this.codeNameEl = getEl('#code-name', this.shadowRoot) as HTMLElement;
         this.codeToolsEl = getEl('#code-tools', this.shadowRoot) as HTMLElement;
         this.codeBodyEl = getEl('#code-body', this.shadowRoot) as HTMLElement;
-        this.highlightedCodeEl = getEl('#highlight-code', this.shadowRoot) as HTMLElement;
+        this.highlightEl = getEl('#highlight', this.shadowRoot) as HTMLElement;
 
         this.codeBodyEl.addEventListener('scroll', () => {
             let flag = this.codeBodyEl.scrollTop + this.codeBodyEl.clientHeight < this.codeBodyEl.scrollHeight;
-            // 检测是否是用户手动滚动
+            // Check if the user manually scrolled
             this.autoScroll = !flag;
         });
     }
     /**
-         * Registers a new language with a set of syntax highlighting rules.
-         * @param name - The name of the programming language.
-         * @param config - Configuration for the language, including rules, theme, and optional CSS.
-         */
+      * Registers a new language with a set of syntax highlighting rules.
+      * @param name - The name of the programming language (e.g., 'javascript', 'html', etc.)
+      * @param config - Configuration for the language, including rules, theme, and optional CSS.
+      */
     static register(name: string, config: LanguageConfig): void {
         // Store the language configuration in the static map
         this.languages.set(name, { ...config });
     }
-    //注册工具箱
+    /**
+     * Registers tools that can be used with the code editor (e.g., copy, download, etc.).
+     * @param items - An array of tool items to register.
+     */
     static addTools(items: toolsItem[]): void {
-        CoaxElem.tools = items;
+        Coax.tools = items;
     }
-    //加入工具箱
+    /**
+     * Mounts the tools to the code tools container.
+     * @param toolItems - An array of tool items to be added to the tools container.
+     */
     mountTools(toolItems: any[]) {
         requestAnimationFrame(() => {
             this.codeToolsEl.innerHTML = '';
@@ -232,29 +239,37 @@ class CoaxElem extends HTMLElement {
             this.codeToolsEl.appendChild(createTools(items));
         });
     }
-    // Called when the element is connected to the DOM
+    /**
+     * Called when the element is connected to the DOM.
+     */
     connectedCallback() {
         this.render();
     }
 
-    // Observed attributes for changes
+    /**
+     * Observed attributes for changes. These include the language, height, tools, and speed.
+     */
     static get observedAttributes() { return ['lang', 'height', 'max-height', 'tools', 'speed']; }
 
     /**
-    * Called when any of the observed attributes change.
-    */
+     * Called when any of the observed attributes change.
+     * @param name - The name of the changed attribute.
+     * @param oldVal - The old value of the attribute.
+     * @param newVal - The new value of the attribute.
+     */
     attributeChangedCallback(name: string, oldVal: string, newVal: string) {
-        if (oldVal === newVal) return;
+        if (oldVal === newVal || !this.canListen) return;
         if (name === 'height' || name === 'max-height') {
             this.updateStyleByRegExp(name, newVal);
         }
 
         if (name === 'speed') {
+            // Convert to integer (0 or 1)
             this.speed = ~~(!!newVal);
         }
 
         if (name === 'lang') {
-            //更新当前语言
+            // Update the language and re-render
             this.lang = newVal;
             this.render();
         }
@@ -262,14 +277,16 @@ class CoaxElem extends HTMLElement {
         if (name === 'tools') {
             if (!newVal) this.codeToolsEl.innerHTML = '';
             const tools = parseClasses(newVal),
-                toolItems = CoaxElem.tools.filter(k => tools.includes(k.name));
+                toolItems = Coax.tools.filter(k => tools.includes(k.name));
             if (!toolItems.length) return;
             this.mountTools(toolItems);
         }
     }
     /**
-      * 使用正则替换基础样式表中的特定属性，避免操作行内样式
-      */
+     * Updates the base style by replacing specific CSS properties using a regular expression.
+     * @param prop - The CSS property name to update (e.g., 'height', 'max-height').
+     * @param value - The new value for the property.
+     */
     private updateStyleByRegExp(prop: string, value: string) {
         // 构建正则：匹配属性名后面跟着冒号，直到分号或换行
         // 例如：height:\s*[^;]+;
@@ -277,11 +294,22 @@ class CoaxElem extends HTMLElement {
         // 替换为新的属性值
         this.baseStylesEl.textContent = this.baseStylesEl.textContent.replace(regex, `;\n${prop}: ${value};`);
     }
+    /**
+     * Retrieves the CSS prefix for the language configuration.
+     * @param config - The language configuration object.
+     * @returns The CSS prefix.
+     */
     getCssPrefix(config: LanguageConfig) {
         return (config?.cssPrefix || this.lang).replace(/[^a-zA-Z0-9_-]/g, '\\$&');
     }
+    /**
+     * Highlights a given string according to the language configuration.
+     * @param string - The string to highlight.
+     * @param config - The language configuration object.
+     * @returns The highlighted string with HTML spans.
+     */
     getHighLightString(string: string, config?: LanguageConfig) {
-        config = config || CoaxElem.languages.get(this.lang);
+        config = config || Coax.languages.get(this.lang);
         if (!config) return string;
         // 如果找到了配置，则进行高亮处理
         const cssPrefix = this.getCssPrefix(config),
@@ -292,29 +320,41 @@ class CoaxElem extends HTMLElement {
             return i !== -1 && config.rules[i] ? `<span class="${NAMESPACE}-${cssPrefix}-${config.rules[i].token}">${match}</span>` : match;
         });
     }
+    /**
+      * Creates a wrapper element for a line of code.
+      * @param index - The line index to assign.
+      * @param startIndex - The starting index for the line.
+      * @returns A div element wrapping the line of code.
+      */
     createLineWrap(index?: number, startIndex?: number) {
         let dataIndex = 0;
         if (index == null && startIndex == null) {
-            dataIndex = this.highlightedCodeEl.children.length;
+            dataIndex = this.highlightEl.children.length;
         } else {
-            const start = startIndex || this.highlightedCodeEl.children.length;
+            const start = startIndex || this.highlightEl.children.length;
             dataIndex = start + (index as number);
         }
         return createEl('div', { 'data-index': dataIndex }, '<div></div>');
     }
+    /**
+      * Fills a line of code with highlighted content.
+      * @param codeWrap - The element that will contain the highlighted line of code.
+      * @param line - The line of code to highlight.
+      * @param config - The language configuration object.
+      */
     getLineToFill(codeWrap: Element, line: string, config?: LanguageConfig) {
-        config = config || CoaxElem.languages.get(this.lang);
+        config = config || Coax.languages.get(this.lang);
         let highlightedLine = this.getHighLightString(line, config);
         // 将高亮后的内容填充到 div 中
         codeWrap.innerHTML = highlightedLine;
     };
     /**
-     * 处理新源码，按行高亮并追加到高亮区域
-     * @param newCode - 新的源码片段
+     * Highlights new source code and appends it to the code body.
+     * @param newCode - The new source code to highlight and append.
      */
     async highlight(newCode: string) {
-        const config = CoaxElem.languages.get(this.lang),
-            startIndex = this.highlightedCodeEl.children.length,
+        const config = Coax.languages.get(this.lang),
+            startIndex = this.highlightEl.children.length,
             // 将新源码按行分割
             newCodeLines = newCode ? newCode.split('\n') : [];
         //更新别名
@@ -328,10 +368,10 @@ class CoaxElem extends HTMLElement {
             const lineWrap = this.createLineWrap(index, startIndex),
                 codeWrap = lineWrap.lastElementChild as Element;
             //标记完成
-            this.closeLine(lineWrap);
+            (lineWrap as any).completed = true;
 
             if (this.hasAttribute('speed')) {
-                this.highlightedCodeEl.appendChild(lineWrap);
+                this.highlightEl.appendChild(lineWrap);
                 //流式打字
                 await typeWriter(lineString, {
                     speed: this.speed,
@@ -344,20 +384,27 @@ class CoaxElem extends HTMLElement {
                 //直接打出
                 this.getLineToFill(codeWrap, lineString, config);
                 //
-                this.highlightedCodeEl.appendChild(lineWrap);
+                this.highlightEl.appendChild(lineWrap);
             }
         }
         //滚动到最底部
         this.autoScrollCode();
         return true;
     }
+
+    /**
+     * Automatically scrolls the code body to the bottom.
+     */
     autoScrollCode() {
         if (this.autoScroll) {
             this.codeBodyEl.scrollTop = this.codeBodyEl.scrollHeight;
         }
     }
+    /**
+     * Injects the theme styles for syntax highlighting (light/dark modes).
+     */
     injectThemeStyles() {
-        const config = CoaxElem.languages.get(this.lang);
+        const config = Coax.languages.get(this.lang);
         if (!config) return;
 
         // Get language name, fallback to 'js' if not provided
@@ -382,7 +429,6 @@ class CoaxElem extends HTMLElement {
                     .${NAMESPACE}-${cssPrefix}-${rule.token} { color: var(--${NAMESPACE}-${cssPrefix}-${rule.token},${rule.dark}); }` : ``} `).join('\n');
         schemeStyles += `}`;
         // Set the inner HTML of the shadow root, including styles and highlighted code
-        // 2. 精确更新 DOM 节点而非重写 ShadowRoot
         this.dynamicStylesEl.textContent = lightStyles + darkStyles + schemeStyles;
 
         //附加主题样式
@@ -392,6 +438,10 @@ class CoaxElem extends HTMLElement {
 
 
     }
+    /**
+     * Updates the alias name for the language based on the configuration.
+     * @param config - The language configuration object.
+     */
     updateName(config: any) {
         if (this.hasAttribute('unnamed')) return;
         if (!config) {
@@ -403,36 +453,35 @@ class CoaxElem extends HTMLElement {
         }
     }
     /**
-         * Renders the highlighted code within the shadow DOM.
-         */
+     * Renders the highlighted code within the shadow DOM.
+     */
     render(code = this.source) {
         //同时多次改变属性，只执行一次
-        // 如果已经在队列中，则直接返回
         if (this._renderQueued) return;
         this._renderQueued = true;
-        // 使用 requestAnimationFrame 将渲染推迟到下一帧
-        requestAnimationFrame(async () => {
-            this.clear();
-            this.injectThemeStyles();
-            //一次性渲染
-            await this.highlight(code);
-            this._renderQueued = false;
-        });
+        this.clear();
+        this.injectThemeStyles();
+        //一次性渲染
+        this.highlight(code);
+        this._renderQueued = false;
     }
+    /**
+     * Clears the current content and resets the state.
+     */
     clear() {
-        this.highlightedCodeEl.innerHTML = this.source = this.lineString = '';
+        this.highlightEl.innerHTML = this.source = this.lineString = '';
     }
     /**
-    * 替换现有的源码并重新渲染
-    * @param newCode - 新的源码
-    */
+     * Replaces the existing code with new source code and re-renders.
+     * @param newCode - The new source code to replace the existing code.
+     */
     async replace(newCode: string) {
         this.clear();
         await this.highlight(newCode);
     }
     /**
-     * 末尾新增源码，仅高亮新增的部分
-     * @param newCode - 新的源码片段
+     * Appends new source code to the current content and highlights only the new portion.
+     * @param newCode - The new source code to append and highlight.
      */
     async append(newCode: string) {
         // 将新的代码追加到现有代码末尾
@@ -440,49 +489,66 @@ class CoaxElem extends HTMLElement {
         // 高亮新的部分
         await this.highlight(newCode);
     }
-    getActiveCodeWrap() {
-        const lastChild = this.highlightedCodeEl.lastElementChild,
-            lastLine = !lastChild || (this.highlightedCodeEl.lastElementChild as any)?.completed ?
+    /**
+     * Retrieves the last line of code that was rendered.
+     * @returns An object containing the line wrapper and code wrapper for the last line.
+     */
+    getLastLine() {
+        const lastChild = this.highlightEl.lastElementChild,
+            lastLine = !lastChild || (this.highlightEl.lastElementChild as any)?.completed ?
                 this.createLineWrap() : lastChild;
         return {
             lineWrap: lastLine,
             codeWrap: lastLine.lastElementChild as Element
         }
     }
-    closeLine(lineWrap?: Element | null) {
-        lineWrap = lineWrap || this.highlightedCodeEl.lastElementChild;
-        lineWrap && ((lineWrap as any).completed = true);
+    /**
+      * Marks the current line as completed and updates the displayed code.
+      */
+    close() {
+        const lineWrap = this.highlightEl.lastElementChild;
+        if (!lineWrap) return;
+        (lineWrap as any).completed = true;
+        //行结束前保存
+        this.lastLineString = this.lineString;
+        this.getLineToFill(lineWrap?.lastElementChild as Element, this.lineString);
+        //一行结束，清空临时行文本
+        this.lineString = '';
     }
-    openLine(lineWrap?: Element | null) {
-        lineWrap = lineWrap || this.highlightedCodeEl.lastElementChild;
-        lineWrap && ((lineWrap as any).completed = false);
+    /**
+     * Reopens the last closed line and restores its original content.
+     */
+    open() {
+        const lineWrap = this.highlightEl.lastElementChild;
+        if (!lineWrap) return;
+        (lineWrap as any).completed = false;
+        //恢复最后一行字符串
+        (lineWrap?.lastElementChild as any).textContent = this.lineString = this.lastLineString;
     }
-    stream(str: string, forceEnd: boolean = false) {
-        const { lineWrap, codeWrap } = this.getActiveCodeWrap();
-        this.highlightedCodeEl.appendChild(lineWrap);
+    /**
+     * Streams a string of code into the component, either appending or closing the current line.
+     * @param str - The code string to stream into the component.
+     * @param forceClose - Forcefully close the line if set to `true`.
+     */
+    stream(str: string, forceClose: boolean = false) {
+        const { lineWrap, codeWrap } = this.getLastLine();
+        this.highlightEl.appendChild(lineWrap);
         //汇集
         this.source += str;
 
         //如果没有遇到换行符号，也可以强制结束
-        forceEnd && this.closeLine(lineWrap);
-
-        if (str.startsWith('\n') || str.startsWith('\r')) {
+        if (forceClose || (str.startsWith('\n') || str.endsWith('\n'))) {
             //标记完成
-            this.closeLine(lineWrap);
-            //渲染
-            this.getLineToFill(codeWrap, this.lineString);
-            //一行结束，清空临时行文本
-            this.lineString = '';
+            this.close();
         } else {
             //插入文本
             codeWrap.innerHTML += str;
             //临时保存行文本
             this.lineString += str;
-
         }
         //滚动到最底部
         this.autoScrollCode();
     }
 }
 
-export default CoaxElem;
+export default Coax;

package/src/modules.js

@@ -1,12 +1,12 @@
 /**
- * @since Last modified: 2026/01/12 08:58:23
+ * @since Last modified: 2026/01/12 14:10:29
  */
 'use strict';
-import CoaxElem from './components/CoaxElem.js';
+import Coax from './components/Coax.js';
 import css from './rules/css.js';
 import html from './rules/html.js';
 import javascript from './rules/javascript.js';
 import markdown from './rules/markdown.js';
 import typescript from './rules/typescript.js';
 import copy from './tools/copy.js';
-export { CoaxElem, copy, css, html, javascript, typescript, markdown, };
+export { Coax, copy, css, html, javascript, typescript, markdown, };

package/src/modules.ts

@@ -1,9 +1,9 @@
 /**
- * @since Last modified: 2026/01/12 08:58:23
+ * @since Last modified: 2026/01/12 14:10:29
  */
 'use strict'
 
-import CoaxElem from './components/CoaxElem.js';
+import Coax from './components/Coax.js';
 import css from './rules/css.js';
 import html from './rules/html.js';
 import javascript from './rules/javascript.js';
@@ -12,7 +12,7 @@ import typescript from './rules/typescript.js';
 import copy from './tools/copy.js';
 
 export {
-  CoaxElem,
+  Coax,
   copy,
   css,
   html,