@codady/coax 0.0.4 → 0.0.6

package/src/components/Coax.js

@@ -1,5 +1,5 @@
 /**
- *  Last modified: 2026/01/12 14:09:42
+ *  Last modified: 2026/01/15 19:21:29
  * Coax - A custom web component for syntax highlighting, code display, and interactive features
  *
  */
@@ -9,6 +9,8 @@ import NAMESPACE from "@codady/utils/namespace";
 import getEl from "@codady/utils/getEl";
 import createTools from "@codady/utils/createTools";
 import createEl from "@codady/utils/createEl";
+import trimEmptyLines from "@codady/utils/trimEmptyLines";
+import escapeHtmlChars from "@codady/utils/escapeHtmlChars";
 class Coax extends HTMLElement {
     // A static Map to hold the configuration for different languages
     static languages = new Map();
@@ -19,7 +21,7 @@ class Coax extends HTMLElement {
     baseStylesEl; // Element for base styles
     themeStylesEl; // Element for theme styles
     dynamicStylesEl; // Element for dynamic styles
-    highlightedCodeEl; // Element that holds the highlighted code
+    highlightEl; // 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)
@@ -30,12 +32,13 @@ class Coax extends HTMLElement {
     lastLineString = ''; // The last line's string
     speed = 5; // Speed of the typing effect (higher is slower)
     autoScroll = true; // Flag to enable/disable auto-scrolling
+    canListen = 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.source = escapeHtmlChars(trimEmptyLines(this.textContent));
         // Initialize the basic structure of the component
         this.shadowRoot.innerHTML = `
             <style id="base-styles">
@@ -166,7 +169,7 @@ class Coax 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
@@ -177,7 +180,7 @@ class Coax extends HTMLElement {
         this.codeNameEl = getEl('#code-name', this.shadowRoot);
         this.codeToolsEl = getEl('#code-tools', this.shadowRoot);
         this.codeBodyEl = getEl('#code-body', this.shadowRoot);
-        this.highlightedCodeEl = getEl('#highlight-code', this.shadowRoot);
+        this.highlightEl = getEl('#highlight', this.shadowRoot);
         this.codeBodyEl.addEventListener('scroll', () => {
             let flag = this.codeBodyEl.scrollTop + this.codeBodyEl.clientHeight < this.codeBodyEl.scrollHeight;
             // Check if the user manually scrolled
@@ -231,7 +234,7 @@ class Coax extends HTMLElement {
      * @param newVal - The new value of the attribute.
      */
     attributeChangedCallback(name, oldVal, newVal) {
-        if (oldVal === newVal)
+        if (oldVal === newVal || !this.canListen)
             return;
         if (name === 'height' || name === 'max-height') {
             this.updateStyleByRegExp(name, newVal);
@@ -302,10 +305,10 @@ class Coax extends HTMLElement {
     createLineWrap(index, startIndex) {
         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;
         }
         return createEl('div', { 'data-index': dataIndex }, '<div></div>');
@@ -316,7 +319,7 @@ class Coax extends HTMLElement {
       * @param line - The line of code to highlight.
       * @param config - The language configuration object.
       */
-    getLineToFill(codeWrap, line, config) {
+    getLineToFillHighLight(codeWrap, line, config) {
         config = config || Coax.languages.get(this.lang);
         let highlightedLine = this.getHighLightString(line, config);
         // 将高亮后的内容填充到 div 中
@@ -327,10 +330,10 @@ class Coax extends HTMLElement {
      * 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 = Coax.languages.get(this.lang), startIndex = this.highlightedCodeEl.children.length, 
+    async highlight(newCode = this.source) {
+        const config = Coax.languages.get(this.lang), startIndex = this.highlightEl.children.length, 
         // 将新源码按行分割
-        newCodeLines = newCode ? newCode.split('\n') : [];
+        newCodeLines = newCode ? newCode.split('\n') : [], hasSpeedAttr = this.hasAttribute('speed'), hasSanitizedAttr = this.hasAttribute('sanitized');
         //更新别名
         this.updateName(config);
         if (!newCodeLines.length)
@@ -338,14 +341,14 @@ class Coax extends HTMLElement {
         // 如果没有找到配置，则输出原始代码，并不进行高亮处理
         for (let [index, lineString] of newCodeLines.entries()) {
             //如果是空行则跳过
-            if (!lineString.trim() && this.hasAttribute('sanitized'))
+            if (!lineString.trim() && hasSanitizedAttr)
                 continue;
             // 创建一个 div 包裹每一行
             const lineWrap = this.createLineWrap(index, startIndex), codeWrap = lineWrap.lastElementChild;
             //标记完成
             lineWrap.completed = true;
-            if (this.hasAttribute('speed')) {
-                this.highlightedCodeEl.appendChild(lineWrap);
+            if (hasSpeedAttr) {
+                this.highlightEl.appendChild(lineWrap);
                 //流式打字
                 await typeWriter(lineString, {
                     speed: this.speed,
@@ -353,13 +356,13 @@ class Coax extends HTMLElement {
                         codeWrap.innerHTML = fullText;
                     }
                 });
-                this.getLineToFill(codeWrap, lineString, config);
+                this.getLineToFillHighLight(codeWrap, lineString, config);
             }
             else {
                 //直接打出
-                this.getLineToFill(codeWrap, lineString, config);
+                this.getLineToFillHighLight(codeWrap, lineString, config);
                 //
-                this.highlightedCodeEl.appendChild(lineWrap);
+                this.highlightEl.appendChild(lineWrap);
             }
         }
         //滚动到最底部
@@ -422,20 +425,30 @@ class Coax extends HTMLElement {
             this.codeNameEl.innerHTML = this.alias;
         }
     }
+    trimLineString(str) {
+        // 删除开头的第一个换行符
+        if (str.startsWith('\n')) {
+            str = str.substring(1);
+        }
+        // 删除结尾的第一个换行符
+        if (str.endsWith('\n')) {
+            str = str.slice(0, -1);
+        }
+        return str;
+    }
     /**
      * Renders the highlighted code within the shadow DOM.
      */
-    render(code = this.source) {
+    render() {
         //同时多次改变属性，只执行一次
         if (this._renderQueued)
             return;
         this._renderQueued = true;
-        // 使用 requestAnimationFrame 将渲染推迟到下一帧
         requestAnimationFrame(async () => {
-            this.clear();
+            this.highlightEl.innerHTML = '';
             this.injectThemeStyles();
             //一次性渲染
-            await this.highlight(code);
+            await this.highlight();
             this._renderQueued = false;
         });
     }
@@ -443,21 +456,27 @@ class Coax extends HTMLElement {
      * Clears the current content and resets the state.
      */
     clear() {
-        this.highlightedCodeEl.innerHTML = this.source = this.lineString = '';
+        this.highlightEl.innerHTML = this.source = this.lineString = '';
     }
     /**
      * 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);
+        newCode = escapeHtmlChars(newCode);
+        this.source = trimEmptyLines(newCode);
+        if (this._renderQueued)
+            return;
+        this.highlightEl.innerHTML = '';
+        //一次性渲染
+        await this.highlight();
     }
     /**
      * 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) {
+        newCode = escapeHtmlChars(newCode);
         // 将新的代码追加到现有代码末尾
         this.source += `\n${newCode}`;
         // 高亮新的部分
@@ -468,7 +487,7 @@ class Coax extends HTMLElement {
      * @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 ?
+        const lastChild = this.highlightEl.lastElementChild, lastLine = !lastChild || this.highlightEl.lastElementChild?.completed ?
             this.createLineWrap() : lastChild;
         return {
             lineWrap: lastLine,
@@ -479,13 +498,13 @@ class Coax extends HTMLElement {
       * Marks the current line as completed and updates the displayed code.
       */
     close() {
-        const lineWrap = this.highlightedCodeEl.lastElementChild;
+        const lineWrap = this.highlightEl.lastElementChild;
         if (!lineWrap)
             return;
         lineWrap.completed = true;
         //行结束前保存
         this.lastLineString = this.lineString;
-        this.getLineToFill(lineWrap?.lastElementChild, this.lineString);
+        this.getLineToFillHighLight(lineWrap?.lastElementChild, this.lineString);
         //一行结束，清空临时行文本
         this.lineString = '';
     }
@@ -493,7 +512,7 @@ class Coax extends HTMLElement {
      * Reopens the last closed line and restores its original content.
      */
     open() {
-        const lineWrap = this.highlightedCodeEl.lastElementChild;
+        const lineWrap = this.highlightEl.lastElementChild;
         if (!lineWrap)
             return;
         lineWrap.completed = false;
@@ -506,20 +525,21 @@ class Coax extends HTMLElement {
      * @param forceClose - Forcefully close the line if set to `true`.
      */
     stream(str, forceClose = false) {
-        const { lineWrap, codeWrap } = this.getLastLine();
-        this.highlightedCodeEl.appendChild(lineWrap);
+        str = escapeHtmlChars(str);
+        const { lineWrap, codeWrap } = this.getLastLine(), isLine = str.startsWith('\n') || str.endsWith('\n');
+        this.highlightEl.appendChild(lineWrap);
         //汇集
         this.source += str;
+        //临时保存行文本
+        this.lineString += isLine ? this.trimLineString(str) : str;
         //如果没有遇到换行符号，也可以强制结束
-        if (forceClose || (str.startsWith('\n') || str.endsWith('\n'))) {
+        if (forceClose || isLine) {
             //标记完成
             this.close();
         }
         else {
             //插入文本
             codeWrap.innerHTML += str;
-            //临时保存行文本
-            this.lineString += str;
         }
         //滚动到最底部
         this.autoScrollCode();

package/src/components/Coax.ts

@@ -1,5 +1,5 @@
 /**
- *  Last modified: 2026/01/12 14:09:42
+ *  Last modified: 2026/01/15 19:21:29
  * Coax - A custom web component for syntax highlighting, code display, and interactive features
  * 
  */
@@ -10,6 +10,8 @@ import NAMESPACE from "@codady/utils/namespace";
 import getEl from "@codady/utils/getEl";
 import createTools, { toolsItem } from "@codady/utils/createTools";
 import createEl from "@codady/utils/createEl";
+import trimEmptyLines from "@codady/utils/trimEmptyLines";
+import escapeHtmlChars from "@codady/utils/escapeHtmlChars";
 
 
 // Define the structure for the language configuration
@@ -39,7 +41,7 @@ class Coax extends HTMLElement {
     private baseStylesEl!: HTMLStyleElement;  // Element for base styles
     private themeStylesEl!: HTMLStyleElement;  // Element for theme styles
     private dynamicStylesEl!: HTMLStyleElement;  // Element for dynamic styles
-    private highlightedCodeEl!: HTMLElement;  // Element that holds the highlighted code
+    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)
@@ -51,13 +53,14 @@ class Coax extends HTMLElement {
     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();
         // 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.source = escapeHtmlChars(trimEmptyLines(this.textContent));
         // Initialize the basic structure of the component
         (this.shadowRoot as any).innerHTML = `
             <style id="base-styles">
@@ -188,7 +191,7 @@ class Coax 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>
         `;
 
@@ -200,7 +203,7 @@ class Coax 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;
@@ -257,7 +260,7 @@ class Coax extends HTMLElement {
      * @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);
         }
@@ -328,9 +331,9 @@ class Coax extends HTMLElement {
     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>');
@@ -341,7 +344,7 @@ class Coax extends HTMLElement {
       * @param line - The line of code to highlight.
       * @param config - The language configuration object.
       */
-    getLineToFill(codeWrap: Element, line: string, config?: LanguageConfig) {
+    getLineToFillHighLight(codeWrap: Element, line: string, config?: LanguageConfig) {
         config = config || Coax.languages.get(this.lang);
         let highlightedLine = this.getHighLightString(line, config);
         // 将高亮后的内容填充到 div 中
@@ -351,26 +354,28 @@ class Coax extends HTMLElement {
      * 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) {
+    async highlight(newCode: string = this.source) {
         const config = Coax.languages.get(this.lang),
-            startIndex = this.highlightedCodeEl.children.length,
+            startIndex = this.highlightEl.children.length,
             // 将新源码按行分割
-            newCodeLines = newCode ? newCode.split('\n') : [];
+            newCodeLines = newCode ? newCode.split('\n') : [],
+            hasSpeedAttr = this.hasAttribute('speed'),
+            hasSanitizedAttr = this.hasAttribute('sanitized');
         //更新别名
-        this.updateName(config)
+        this.updateName(config); 
         if (!newCodeLines.length) return true;
         // 如果没有找到配置，则输出原始代码，并不进行高亮处理
         for (let [index, lineString] of newCodeLines.entries()) {
             //如果是空行则跳过
-            if (!lineString.trim() && this.hasAttribute('sanitized')) continue;
+            if (!lineString.trim() && hasSanitizedAttr) continue;
             // 创建一个 div 包裹每一行
             const lineWrap = this.createLineWrap(index, startIndex),
                 codeWrap = lineWrap.lastElementChild as Element;
             //标记完成
             (lineWrap as any).completed = true;
 
-            if (this.hasAttribute('speed')) {
-                this.highlightedCodeEl.appendChild(lineWrap);
+            if (hasSpeedAttr) {
+                this.highlightEl.appendChild(lineWrap);
                 //流式打字
                 await typeWriter(lineString, {
                     speed: this.speed,
@@ -378,12 +383,12 @@ class Coax extends HTMLElement {
                         codeWrap.innerHTML = fullText;
                     }
                 });
-                this.getLineToFill(codeWrap, lineString, config);
+                this.getLineToFillHighLight(codeWrap, lineString, config);
             } else {
                 //直接打出
-                this.getLineToFill(codeWrap, lineString, config);
+                this.getLineToFillHighLight(codeWrap, lineString, config);
                 //
-                this.highlightedCodeEl.appendChild(lineWrap);
+                this.highlightEl.appendChild(lineWrap);
             }
         }
         //滚动到最底部
@@ -451,41 +456,60 @@ class Coax extends HTMLElement {
             this.codeNameEl.innerHTML = this.alias;
         }
     }
+  
+    trimLineString(str: string) {
+        // 删除开头的第一个换行符
+        if (str.startsWith('\n')) {
+            str = str.substring(1);
+        }
+
+        // 删除结尾的第一个换行符
+        if (str.endsWith('\n')) {
+            str = str.slice(0, -1);
+        }
+
+        return str;
+    }
     /**
      * Renders the highlighted code within the shadow DOM.
      */
-    render(code = this.source) {
+    render() {
         //同时多次改变属性，只执行一次
         if (this._renderQueued) return;
         this._renderQueued = true;
-        // 使用 requestAnimationFrame 将渲染推迟到下一帧
         requestAnimationFrame(async () => {
-            this.clear();
+            this.highlightEl.innerHTML = '';
             this.injectThemeStyles();
             //一次性渲染
-            await this.highlight(code);
+            await this.highlight();
             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 = '';
     }
     /**
      * 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);
+        newCode = escapeHtmlChars(newCode);
+        this.source = trimEmptyLines(newCode);
+        if (this._renderQueued) return;
+        this.highlightEl.innerHTML = '';
+        //一次性渲染
+        await this.highlight();
     }
     /**
      * 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) {
+        newCode = escapeHtmlChars(newCode);
         // 将新的代码追加到现有代码末尾
         this.source += `\n${newCode}`;
         // 高亮新的部分
@@ -496,8 +520,8 @@ class Coax extends HTMLElement {
      * @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 as any)?.completed ?
+        const lastChild = this.highlightEl.lastElementChild,
+            lastLine = !lastChild || (this.highlightEl.lastElementChild as any)?.completed ?
                 this.createLineWrap() : lastChild;
         return {
             lineWrap: lastLine,
@@ -508,12 +532,12 @@ class Coax extends HTMLElement {
       * Marks the current line as completed and updates the displayed code.
       */
     close() {
-        const lineWrap = this.highlightedCodeEl.lastElementChild;
+        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.getLineToFillHighLight(lineWrap?.lastElementChild as Element, this.lineString);
         //一行结束，清空临时行文本
         this.lineString = '';
     }
@@ -521,7 +545,7 @@ class Coax extends HTMLElement {
      * Reopens the last closed line and restores its original content.
      */
     open() {
-        const lineWrap = this.highlightedCodeEl.lastElementChild;
+        const lineWrap = this.highlightEl.lastElementChild;
         if (!lineWrap) return;
         (lineWrap as any).completed = false;
         //恢复最后一行字符串
@@ -533,20 +557,23 @@ class Coax extends HTMLElement {
      * @param forceClose - Forcefully close the line if set to `true`.
      */
     stream(str: string, forceClose: boolean = false) {
-        const { lineWrap, codeWrap } = this.getLastLine();
-        this.highlightedCodeEl.appendChild(lineWrap);
+        str = escapeHtmlChars(str);
+        const { lineWrap, codeWrap } = this.getLastLine(),
+            isLine = str.startsWith('\n') || str.endsWith('\n');
+        this.highlightEl.appendChild(lineWrap);
         //汇集
         this.source += str;
 
+        //临时保存行文本
+        this.lineString += isLine ? this.trimLineString(str) : str;
+
         //如果没有遇到换行符号，也可以强制结束
-        if (forceClose || (str.startsWith('\n') || str.endsWith('\n'))) {
+        if (forceClose || isLine) {
             //标记完成
             this.close();
         } else {
             //插入文本
             codeWrap.innerHTML += str;
-            //临时保存行文本
-            this.lineString += str;
         }
         //滚动到最底部
         this.autoScrollCode();

package/src/modules.js

@@ -1,5 +1,5 @@
 /**
- * @since Last modified: 2026/01/12 14:10:29
+ * @since Last modified: 2026/01/15 19:21:31
  */
 'use strict';
 import Coax from './components/Coax.js';

package/src/modules.ts

@@ -1,5 +1,5 @@
 /**
- * @since Last modified: 2026/01/12 14:10:29
+ * @since Last modified: 2026/01/15 19:21:31
  */
 'use strict'