@codady/coax 0.0.3 → 0.0.4

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

@@ -1,5 +1,7 @@
 /**
- *  Last modified: 2026/01/12 09:40:20
+ *  Last modified: 2026/01/12 14:09:42
+ * Coax - A custom web component for syntax highlighting, code display, and interactive features
+ *
  */
 import typeWriter from "@codady/utils/typeWriter";
 import parseClasses from "@codady/utils/parseClasses";
@@ -7,36 +9,34 @@ import NAMESPACE from "@codady/utils/namespace";
 import getEl from "@codady/utils/getEl";
 import createTools from "@codady/utils/createTools";
 import createEl from "@codady/utils/createEl";
-class CoaxElem extends HTMLElement {
+class Coax extends HTMLElement {
     // A static Map to hold the configuration for different languages
     static languages = new Map();
+    // A static array to hold the tools registered with the component
     static tools = [];
-    source;
-    _renderQueued = false;
-    baseStylesEl;
-    themeStylesEl;
-    dynamicStylesEl;
-    highlightedCodeEl;
-    headerEl;
-    codeNameEl;
-    codeToolsEl;
-    codeBodyEl;
-    alias;
-    lineString;
-    speed;
-    autoScroll;
+    source; // Source code content to be highlighted
+    _renderQueued = false; // Flag to prevent multiple render requests
+    baseStylesEl; // Element for base styles
+    themeStylesEl; // Element for theme styles
+    dynamicStylesEl; // Element for dynamic styles
+    highlightedCodeEl; // Element that holds the highlighted code
+    headerEl; // Header element (for code name, tools, etc.)
+    codeNameEl; // Code name element (shows language or alias)
+    codeToolsEl; // Code tools element (for interactive tools like copy)
+    codeBodyEl; // Code body element (the container for the code)
+    lang = 'plain'; // Language of the code (default is plain text)
+    alias = 'Plain Text'; // Alias name for the language (default is 'Plain Text')
+    lineString = ''; // The current line's string being typed
+    lastLineString = ''; // The last line's string
+    speed = 5; // Speed of the typing effect (higher is slower)
+    autoScroll = true; // Flag to enable/disable auto-scrolling
     constructor() {
         super();
         // Attach a Shadow DOM to the custom element
         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.innerHTML = `
             <style id="base-styles">
                 :host { 
@@ -169,7 +169,7 @@ class CoaxElem extends HTMLElement {
                 <pre><code id="highlight-code"></code></pre>
             </div>
         `;
-        // 缓存引用
+        // Cache references to various elements
         this.baseStylesEl = getEl('#base-styles', this.shadowRoot);
         this.themeStylesEl = getEl('#theme-styles', this.shadowRoot);
         this.dynamicStylesEl = getEl('#dynamic-styles', this.shadowRoot);
@@ -180,24 +180,30 @@ class CoaxElem extends HTMLElement {
         this.highlightedCodeEl = getEl('#highlight-code', this.shadowRoot);
         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, config) {
         // 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) {
-        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) {
         requestAnimationFrame(() => {
             this.codeToolsEl.innerHTML = '';
@@ -208,15 +214,22 @@ 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, oldVal, newVal) {
         if (oldVal === newVal)
             return;
@@ -224,25 +237,28 @@ class CoaxElem extends HTMLElement {
             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();
         }
         if (name === 'tools') {
             if (!newVal)
                 this.codeToolsEl.innerHTML = '';
-            const tools = parseClasses(newVal), toolItems = CoaxElem.tools.filter(k => tools.includes(k.name));
+            const tools = parseClasses(newVal), 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.
+     */
     updateStyleByRegExp(prop, value) {
         // 构建正则：匹配属性名后面跟着冒号，直到分号或换行
         // 例如：height:\s*[^;]+;
@@ -250,11 +266,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) {
         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, config) {
-        config = config || CoaxElem.languages.get(this.lang);
+        config = config || Coax.languages.get(this.lang);
         if (!config)
             return string;
         // 如果找到了配置，则进行高亮处理
@@ -266,6 +293,12 @@ 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, startIndex) {
         let dataIndex = 0;
         if (index == null && startIndex == null) {
@@ -277,19 +310,25 @@ class CoaxElem extends HTMLElement {
         }
         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, line, config) {
-        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) {
-        const config = CoaxElem.languages.get(this.lang), startIndex = this.highlightedCodeEl.children.length, 
+        const config = Coax.languages.get(this.lang), startIndex = this.highlightedCodeEl.children.length, 
         // 将新源码按行分割
         newCodeLines = newCode ? newCode.split('\n') : [];
         //更新别名
@@ -304,7 +343,7 @@ class CoaxElem extends HTMLElement {
             // 创建一个 div 包裹每一行
             const lineWrap = this.createLineWrap(index, startIndex), codeWrap = lineWrap.lastElementChild;
             //标记完成
-            this.closeLine(lineWrap);
+            lineWrap.completed = true;
             if (this.hasAttribute('speed')) {
                 this.highlightedCodeEl.appendChild(lineWrap);
                 //流式打字
@@ -327,13 +366,19 @@ class CoaxElem extends HTMLElement {
         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
@@ -355,13 +400,16 @@ 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;
         //附加主题样式
         if (config?.themeStyles) {
             this.themeStylesEl.textContent = config.themeStyles;
         }
     }
+    /**
+     * Updates the alias name for the language based on the configuration.
+     * @param config - The language configuration object.
+     */
     updateName(config) {
         if (this.hasAttribute('unnamed'))
             return;
@@ -375,11 +423,10 @@ 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;
@@ -392,20 +439,23 @@ class CoaxElem extends HTMLElement {
             this._renderQueued = false;
         });
     }
+    /**
+     * Clears the current content and resets the state.
+     */
     clear() {
         this.highlightedCodeEl.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) {
         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) {
         // 将新的代码追加到现有代码末尾
@@ -413,7 +463,11 @@ class CoaxElem extends HTMLElement {
         // 高亮新的部分
         await this.highlight(newCode);
     }
-    getActiveCodeWrap() {
+    /**
+     * 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.highlightedCodeEl.lastElementChild, lastLine = !lastChild || this.highlightedCodeEl.lastElementChild?.completed ?
             this.createLineWrap() : lastChild;
         return {
@@ -421,28 +475,45 @@ class CoaxElem extends HTMLElement {
             codeWrap: lastLine.lastElementChild
         };
     }
-    closeLine(lineWrap) {
-        lineWrap = lineWrap || this.highlightedCodeEl.lastElementChild;
-        lineWrap && (lineWrap.completed = true);
+    /**
+      * Marks the current line as completed and updates the displayed code.
+      */
+    close() {
+        const lineWrap = this.highlightedCodeEl.lastElementChild;
+        if (!lineWrap)
+            return;
+        lineWrap.completed = true;
+        //行结束前保存
+        this.lastLineString = this.lineString;
+        this.getLineToFill(lineWrap?.lastElementChild, this.lineString);
+        //一行结束，清空临时行文本
+        this.lineString = '';
     }
-    openLine(lineWrap) {
-        lineWrap = lineWrap || this.highlightedCodeEl.lastElementChild;
-        lineWrap && (lineWrap.completed = false);
+    /**
+     * Reopens the last closed line and restores its original content.
+     */
+    open() {
+        const lineWrap = this.highlightedCodeEl.lastElementChild;
+        if (!lineWrap)
+            return;
+        lineWrap.completed = false;
+        //恢复最后一行字符串
+        (lineWrap?.lastElementChild).textContent = this.lineString = this.lastLineString;
     }
-    stream(str, forceEnd = false) {
-        const { lineWrap, codeWrap } = this.getActiveCodeWrap();
+    /**
+     * 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, forceClose = false) {
+        const { lineWrap, codeWrap } = this.getLastLine();
         this.highlightedCodeEl.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 {
             //插入文本
@@ -454,4 +525,4 @@ class CoaxElem extends HTMLElement {
         this.autoScrollCode();
     }
 }
-export default CoaxElem;
+export default Coax;