@codady/coax 0.0.2 → 0.0.4

package/src/components/Coax.js

@@ -0,0 +1,528 @@
+/**
+ *  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";
+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 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; // 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, '') || '';
+        // Initialize the basic structure of the component
+        this.shadowRoot.innerHTML = `
+            <style id="base-styles">
+                :host { 
+                    --border-width:1px;
+                    --border-style:solid;
+                    --radius:9px;
+                    --height:auto;
+                    --max-height:500px;
+                    --radius:9px;
+                    --padding:1em;
+                    --font-size:16px;
+                    --line-height:1.8;
+                    --background:rgb(247, 247, 247);
+                    --border-color:rgb(224, 224, 224);
+                    --color-code:rgb(51, 51, 51);
+                    --color-index:rgb(153, 153, 153);
+                    --color-stripe:rgba(0,0,0,0.04);
+                    --color-hover:rgba(0,0,0,0.06);
+                }           
+               :host([scheme="dark"]){
+                    --background: #282c34;
+                    --border-color: transparent;
+                    --color-code: #abb2bf;
+                    --color-index:rgb(153, 153, 153);
+                    --color-stripe:rgba(255,255,255,0.04);
+                    --color-hover:rgba(255,255,255,0.06);
+               }
+                @media (prefers-color-scheme: dark) {
+                    :host{
+                        --background: #282c34;
+                        --border-color: transparent;
+                        --color-code: #abb2bf;
+                        --color-index:rgb(153, 153, 153);
+                        --color-stripe:rgba(255,255,255,0.04);
+                        --color-hover:rgba(255,255,255,0.06);
+                    }
+                }
+                :host {
+                    font-size: var(--${NAMESPACE}-code-font-size,var(--font-size));
+                    display: block; 
+                    box-sizing:border-box;
+                    background:var(--${NAMESPACE}-code-background-color,var(--background));
+                    color:var(--${NAMESPACE}-code-color,var(--color-code));
+                    border:var(--${NAMESPACE}-code-border-width,var(--border-width)) var(--${NAMESPACE}-code-border-style,var(--border-style)) var(--${NAMESPACE}-code-border-color,var(--border-color));
+                    transition: border-color 0.3s ease,color 0.3s ease;  
+                    border-radius: var(--${NAMESPACE}-code-radius,var(--radius));
+                }
+                #code-header{
+                    line-height:calc(var(--${NAMESPACE}-code-line-height,var(--line-height))*1.5);
+                    padding-inline-start:var(--${NAMESPACE}-code-padding,var(--padding));
+                    display:flex;
+                    
+                    >:first-child{
+                        flex:auto;
+                    }
+                }
+                #code-body{
+                    padding: var(--${NAMESPACE}-code-padding,var(--padding)) 0;
+                    height:var(--${NAMESPACE}-code-height,var(--height));
+                    max-height:var(--${NAMESPACE}-code-max-height,var(--max-height));
+                    overflow:auto;
+                }
+                pre,code{
+                    font-family:"Consolas", "Monaco", "Andale Mono", "Ubuntu Mono", "monospace";
+                    margin:0; padding:0;
+                }
+                code>div{
+                    display:flex;
+                    padding:0 var(--${NAMESPACE}-code-padding,var(--padding));
+                    line-height: var(--${NAMESPACE}-code-line-height,var(--line-height));
+                    box-sizing:border-box;
+                    
+                    >div{
+                        flex:auto;
+                    }
+                }
+                code>div>div:empty:before{
+                    content:' ';
+                }
+                :host([indexed]) code>div:before{
+                    display:inline-flex;
+                    color:var(--color-index);
+                    content: attr(data-index);
+                    min-width:var(--${NAMESPACE}-code-index-width,2em);
+                    margin-inline-end:var(--${NAMESPACE}-code-padding,8px);
+                }
+                :host([striped]) code>div:nth-child(odd){
+                    background-color:var(--color-stripe);
+                }
+                :host([hoverable]) code>div:hover{
+                    background-color:var(--color-hover);
+                }
+                :host([wrapped]) code>div>div{
+                    white-space: pre-wrap;
+                }
+                :host([unnamed]) #code-name{
+                    display:none;
+                }
+                .${NAMESPACE}-box-tools{
+                    >*{
+                        font-size:14px;
+                        display:inline-flex;
+                        align-items:center;
+                        justify-content:center;
+                        height:2em;
+                        line-height:2em;
+                        aspect-ratio:1/1;
+                        margin-inline-end:8px;
+                        transition:all 200ms ease;
+                        border-radius:6px;
+                        &:hover{
+                            cursor:pointer;
+                            background-color:rgba(0,0,0,.04);
+                        }
+                    }
+                    [rep=icon]{
+                        display:inline-flex;
+                        align-items:center;
+                        justify-content:center;
+                    }
+                }
+                [disabled]{
+                    pointer-event:none;
+                }
+            </style>
+            <style id="dynamic-styles"></style>
+            <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>
+            </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);
+        this.headerEl = getEl('#code-header', this.shadowRoot);
+        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.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 (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) {
+        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 = '';
+            let items = toolItems.map(k => {
+                k.action = k.action.bind(this);
+                return k;
+            });
+            this.codeToolsEl.appendChild(createTools(items));
+        });
+    }
+    /**
+     * Called when the element is connected to the DOM.
+     */
+    connectedCallback() {
+        this.render();
+    }
+    /**
+     * 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.
+     * @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;
+        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();
+        }
+        if (name === 'tools') {
+            if (!newVal)
+                this.codeToolsEl.innerHTML = '';
+            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*[^;]+;
+        const regex = new RegExp(`;\\n\\s*${prop}:\\s*[^;]+;`, 'g');
+        // 替换为新的属性值
+        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 || Coax.languages.get(this.lang);
+        if (!config)
+            return string;
+        // 如果找到了配置，则进行高亮处理
+        const cssPrefix = this.getCssPrefix(config), 
+        // 获取用于语法高亮的正则表达式
+        combinedRegex = new RegExp(config.rules.map((r) => `(${r.pattern.source})`).join('|'), 'g');
+        return string.replace(combinedRegex, (match, ...args) => {
+            const i = args.findIndex(val => val !== undefined);
+            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) {
+            dataIndex = this.highlightedCodeEl.children.length;
+        }
+        else {
+            const start = startIndex || this.highlightedCodeEl.children.length;
+            dataIndex = start + index;
+        }
+        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 || Coax.languages.get(this.lang);
+        let highlightedLine = this.getHighLightString(line, config);
+        // 将高亮后的内容填充到 div 中
+        codeWrap.innerHTML = highlightedLine;
+    }
+    ;
+    /**
+     * 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, 
+        // 将新源码按行分割
+        newCodeLines = newCode ? newCode.split('\n') : [];
+        //更新别名
+        this.updateName(config);
+        if (!newCodeLines.length)
+            return true;
+        // 如果没有找到配置，则输出原始代码，并不进行高亮处理
+        for (let [index, lineString] of newCodeLines.entries()) {
+            //如果是空行则跳过
+            if (!lineString.trim() && this.hasAttribute('sanitized'))
+                continue;
+            // 创建一个 div 包裹每一行
+            const lineWrap = this.createLineWrap(index, startIndex), codeWrap = lineWrap.lastElementChild;
+            //标记完成
+            lineWrap.completed = true;
+            if (this.hasAttribute('speed')) {
+                this.highlightedCodeEl.appendChild(lineWrap);
+                //流式打字
+                await typeWriter(lineString, {
+                    speed: this.speed,
+                    onDuringType: (char, fullText) => {
+                        codeWrap.innerHTML = fullText;
+                    }
+                });
+                this.getLineToFill(codeWrap, lineString, config);
+            }
+            else {
+                //直接打出
+                this.getLineToFill(codeWrap, lineString, config);
+                //
+                this.highlightedCodeEl.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 = Coax.languages.get(this.lang);
+        if (!config)
+            return;
+        // Get language name, fallback to 'js' if not provided
+        let cssPrefix = this.getCssPrefix(config), 
+        //Generate dynamic CSS classes for each syntax rule
+        // 为 rules 中的每一个 name 生成类似 .hl-name { color: var(--ax-code-name); }
+        lightStyles = config.rules.map((rule) => `
+                .${NAMESPACE}-${cssPrefix}-${rule.token} { color: var(--${NAMESPACE}-${cssPrefix}-${rule.token}${rule.light ? ',' + rule.light : ''});}`).join('\n'), darkStyles = '', schemeStyles = '';
+        darkStyles += `:host([scheme="dark"]){`;
+        darkStyles += config.rules.map((rule) => `
+                ${rule.light ? `
+                    .${NAMESPACE}-${cssPrefix}-${rule.token} {color: var(--${NAMESPACE}-${cssPrefix}-${rule.token},${rule.dark});}` : ``}`).join('\n');
+        darkStyles += `}`;
+        schemeStyles = `@media (prefers-color-scheme: dark){
+                                :host{
+            `;
+        schemeStyles += config.rules.map((rule) => `
+                ${rule.light ? `
+                    .${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
+        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;
+        if (!config) {
+            this.codeNameEl.innerHTML = 'Plain Text';
+        }
+        else {
+            //更新别名
+            this.alias = config.alias || this.lang;
+            this.codeNameEl.innerHTML = this.alias;
+        }
+    }
+    /**
+     * 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;
+        });
+    }
+    /**
+     * Clears the current content and resets the state.
+     */
+    clear() {
+        this.highlightedCodeEl.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);
+    }
+    /**
+     * 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) {
+        // 将新的代码追加到现有代码末尾
+        this.source += `\n${newCode}`;
+        // 高亮新的部分
+        await this.highlight(newCode);
+    }
+    /**
+     * 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 {
+            lineWrap: lastLine,
+            codeWrap: lastLine.lastElementChild
+        };
+    }
+    /**
+      * 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 = '';
+    }
+    /**
+     * 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;
+    }
+    /**
+     * 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;
+        //如果没有遇到换行符号，也可以强制结束
+        if (forceClose || (str.startsWith('\n') || str.endsWith('\n'))) {
+            //标记完成
+            this.close();
+        }
+        else {
+            //插入文本
+            codeWrap.innerHTML += str;
+            //临时保存行文本
+            this.lineString += str;
+        }
+        //滚动到最底部
+        this.autoScrollCode();
+    }
+}
+export default Coax;