@gitsense/gsc-utils 0.2.24 → 0.2.27

package/src/DomUtils.js

@@ -0,0 +1,559 @@
+/**
+ * Component: DomUtils Helper Functions
+ * Block-UUID: 9a8e8e8e-8b15-4346-bbfa-740e6a5d2d79
+ * Parent-UUID: 8a528728-ce54-4445-946d-1743fb4b16be
+ * Version: 1.3.0
+ * Description: Provides helper functions for creating and manipulating DOM elements.
+ * Language: JavaScript
+ * Created-at: 2025-12-14T04:18:40.180Z
+ * Authors: Gemini 2.5 Pro (v1.0.0), Gemini 2.5 Flash (v1.1.0), Qwen 3 Coder 480B - Cerebras (v1.2.0), GLM-4.6 (v1.2.1), GLM-4.6 (v1.3.0)
+ */
+
+
+function createElement(type, params) {
+    let elem = document.createElement(type);
+
+    if (!params) return elem;
+
+    // Extract all standard properties
+    let {
+        id,
+        ariaLabel,
+        xmlns,
+        role,
+        html,
+        text,
+        cls,
+        className,
+        colSpan,
+        pointerEvents,
+        title,
+        style,
+        append,
+        type: inputType,
+        value,
+        name,
+        checked,
+        selected, 
+        disabled, 
+        placeholder,
+        "for": _for,
+        "data-message-id": dmi,
+        "data-message-role": dmr,
+        attrs = {},
+        dataset,
+        rows
+    } = params;
+
+    // Set standard attributes
+    if (id != null) elem.id = id;
+    if (ariaLabel) elem.setAttribute("aria-label", ariaLabel);
+    if (xmlns) elem.setAttribute("xmlns", xmlns);
+    if (params.viewBox) elem.setAttribute("viewBox", params.viewBox);
+    if (params.fill) elem.setAttribute("fill", params.fill);
+    if (role) elem.setAttribute("role", role);
+    if (placeholder) elem.setAttribute("placeholder", placeholder);
+    if (cls || className) elem.setAttribute("class", cls || className);
+    if (pointerEvents) elem.setAttribute("pointer-events", pointerEvents);
+    if (title != null) elem.setAttribute("title", title);
+    if (inputType) elem.setAttribute("type", inputType);
+    if (name != null) elem.setAttribute("name", name);
+    if (params.width) elem.setAttribute("width", params.width);
+    if (params.height) elem.setAttribute("height", params.height);
+    if (params.stroke) elem.setAttribute("stroke", params.stroke);
+    if (value != null) elem.value = value;
+    if (checked != null && checked) elem.checked = true; // Use property for checked
+    if (selected != null && selected) elem.selected = true; // Use property for selected
+    if (disabled != null) elem.disabled = disabled; // Use property for disabled
+    if (dmi != null) elem.setAttribute("data-message-id", dmi);
+    if (dmr != null) elem.setAttribute("data-message-role", dmr);
+    if (_for != null ) elem.setAttribute("for", _for);
+    if (params.strokeWidth) elem.setAttribute("stroke-width", params.strokeWidth);
+    if (params.strokeLinecap) elem.setAttribute("stroke-linecap", params.strokeLinecap);
+    if (params.strokeLinejoin) elem.setAttribute("stroke-linejoin", params.strokeLinejoin);
+    if (colSpan != null) elem.colSpan = colSpan;
+    if (rows) elem.setAttribute("rows", params.rows);
+
+    // Set content
+    if (html != null) {
+        if (typeof html === "object" && html instanceof Node) { // Ensure html is a Node
+            elem.appendChild(html);
+        } else if (typeof html === "string") {
+            // For SVG elements, use innerHTML to support path elements
+            if (type === 'svg' && params.innerHTML) {
+                elem.innerHTML = params.innerHTML;
+            }
+            elem.innerHTML = html;
+        }
+    } else if (text != null) {
+        elem.innerText = text;
+    }
+
+    // Set style properties
+    if (style) {
+        for (const name in style) {
+            elem.style[name] = style[name];
+        }
+    }
+
+    // Handle append (now supports both arrays and single elements)
+    if (append) {
+        const appendItems = Array.isArray(append) ? append : [append];
+        appendItems.forEach(e => {
+            if (e instanceof Node) { // Ensure item to append is a Node
+                elem.appendChild(e);
+            } else if (e !== undefined && e !== null) {
+                 console.warn("Attempted to append non-Node item:", e);
+            }
+        });
+    }
+
+    // Set additional attributes from attrs object
+    if (attrs && typeof attrs === 'object') {
+        for (const [key, value] of Object.entries(attrs)) {
+            if (value !== undefined && value !== null) {
+                // Skip if already set by standard properties or handled directly
+                if (!['id', 'class', 'role', 'aria-label', 'title', 'style', 'selected', 'disabled', 'value', 'name', 'type', 'for'].includes(key) && !key.startsWith('data-')) {
+                    elem.setAttribute(key, value);
+                }
+            }
+        }
+    }
+
+    // Handle dataset properties
+    if (dataset && typeof dataset === 'object') {
+        for (const [key, value] of Object.entries(dataset)) {
+            if (value !== undefined && value !== null) {
+                elem.dataset[key] = value;
+            }
+        }
+    }
+
+    // Handle event handlers (like onclick, onchange, etc.)
+    for (const [key, value] of Object.entries(params)) {
+        // Check if the property is an event handler (starts with 'on')
+        if (key.startsWith('on') && typeof value === 'function') {
+            const eventName = key.slice(2).toLowerCase(); // Remove 'on' prefix and convert to lowercase
+            elem.addEventListener(eventName, value);
+        }
+    }
+
+    return elem;
+}
+
+// Update all creator functions to pass through attrs:
+const h = {
+    elemById: (id) => {
+        return document.getElementById(id);
+    },
+    createA: (params) => {
+        return h.createLink(params);
+    },
+    createArticle: (params) => {
+        return createElement("article", params);
+    },
+    createBr: () => {
+        return createElement("br");
+    },
+    createBreak: () => {
+        return createElement("br");
+    },
+    createButton: (params) => {
+        return createElement("button", params);
+    },
+    createCheckbox: (params) => {
+        // Use createElement and let it handle attributes like checked/disabled
+        return createElement("input", { ...params, type: "checkbox" });
+    },
+    createCode: (params) => {
+        return createElement("code", params);
+    },
+    createDetail: (params) => {
+        return createElement("details", params);
+    },
+    createDiv: (params) => {
+        return createElement("div", params);
+    },
+    createEm: (params) => { // Added
+        return createElement("em", params);
+    },
+    createForm: (params) => {
+        return createElement("form", params);
+    },
+    createInput: (params) => {
+        return createElement("input", params);
+    },
+    createImg : (params) => {
+        const img = createElement("img", params);
+        // src is handled by createElement via attrs or direct property if needed
+        return img;
+    },
+    createH1: (params) => {
+        return createElement("h1", params);
+    },
+    createH2: (params) => {
+        return createElement("h2", params);
+    },
+    createH3: (params) => {
+        return createElement("h3", params);
+    },
+    createH4: (params) => {
+        return createElement("h4", params);
+    },
+    createH5: (params) => {
+        return createElement("h5", params);
+    },
+    createHeader: (header, params) => {
+        // Ensure header is a string like 'h1', 'h2' etc.
+        if (typeof header === 'string' && /^h[1-6]$/i.test(header)) {
+             return createElement(header, params);
+        }
+        console.error("Invalid header type provided to createHeader:", header);
+        return createElement("div", params); // Fallback or throw error
+    },
+    createHr: (params) => {
+        return createElement("hr", params);
+    },
+    createLabel : (params) => {
+        // 'for' is handled by createElement
+        return createElement("label", params);
+    },
+    createLI: (params) => {
+        return createElement("li", params);
+    },
+    createLi: (params) => { // Alias for createLI
+        return createElement("li", params);
+    },
+    createLink: (params) => {
+        const link = createElement("a", params);
+        if (params?.href) link.href = params.href;
+        if (params?.target) link.target = params.target;
+        return link;
+    },
+    createNav: (params) => {
+        return createElement("nav", params);
+    },
+    createOl: (params) => {
+        return createElement("ol", params);
+    },
+    createOL: (params) => {
+        return createElement("ol", params);
+    },
+    createOption: (params) => { // Added
+        // value, text, selected are handled by createElement
+        return createElement("option", params);
+    },
+    createP: (params) => {
+        return createElement("p", params);
+    },
+    createParagraph: (params) => { // Alias for createP
+        return createElement("p", params);
+    },
+    createPre: (params) => {
+        return createElement("pre", params);
+    },
+    createSelect: (params) => { // Added
+        // name, disabled etc handled by createElement
+        const select = createElement("select", params);
+        
+        // Handle options array if provided
+        if (params && params.options && Array.isArray(params.options)) {
+            params.options.forEach(option => {
+                if (option && typeof option === 'object') {
+                    const optionElement = createElement("option", {
+                        value: option.value,
+                        text: option.text,
+                        selected: option.selected
+                    });
+                    select.appendChild(optionElement);
+                }
+            });
+        }
+        
+        return select;
+    },
+    createSpan: (params) => {
+        return createElement("span", params);
+    },
+    createSvg: (params) => {
+        // Create SVG element with xmlns attribute
+        const svgParams = { ...params, xmlns: "http://www.w3.org/2000/svg" };
+        const svg = createElement("svg", svgParams);
+        return svg;
+    },
+    createStrong: (params) => { // Added
+        return createElement("strong", params);
+    },
+    createSummary: (params) => {
+        return createElement("summary", params);
+    },
+    createSup: (params) => {
+        return createElement("sup", params);
+    },
+    createText: (text) => {
+        return document.createTextNode(text);
+    },
+    createTextarea: (params) => {
+        const textArea = createElement("textarea", params);
+        return textArea;
+    },
+    createTextArea: (params) => {
+        const textArea = createElement("textarea", params);
+        return textArea;
+    },
+    createTextNode: (text) => {
+        return document.createTextNode(text);
+    },
+    createTable: (params) => {
+        return createElement("table", params);
+    },
+    createTableBody: (params) => {
+        return createElement("tbody", params);
+    },
+    createTableCell: (params) => {
+        return createElement("td", params);
+    },
+    createTableHead: (params) => {
+        return createElement("thead", params);
+    },
+    createTableHeadCell: (params) => {
+        return createElement("th", params);
+    },
+    createTbody: (params) => {
+        return createElement("tbody", params);
+    },
+    createTd: (params) => {
+        return createElement("td", params);
+    },
+    createTh: (params) => {
+        return createElement("th", params);
+    },
+    createThead: (params) => {
+        return createElement("thead", params);
+    },
+    createTr: (params) => {
+        return createElement("tr", params);
+    },
+    createTableRow: (params) => {
+        return createElement("tr", params);
+    },
+    createTextInput: (params) => {
+        // Use createElement and let it handle attributes like value/disabled
+        return createElement("input", { ...params, type: "text" });
+    },
+    createUl: (params) => {
+        return createElement("ul", params);
+    },
+    createUL: (params) => {
+        return createElement("ul", params);
+    },
+    hide: (elem) => {
+        if (elem && elem.style) {
+            elem.style.display = "none";
+        }
+    },
+    show: (elem) => {
+         if (elem && elem.style) {
+            elem.style.display = ""; // Reset to default display
+         }
+    },
+    updateDOM: (sourceNode, targetNode) => {
+        // Step 1: Check if the node type or tag name is different
+        if (!sourceNode || !targetNode) return; // Basic guard
+        if (sourceNode.nodeType !== targetNode.nodeType || sourceNode.nodeName !== targetNode.nodeName) {
+            targetNode.replaceWith(sourceNode.cloneNode(true));
+            return;
+        }
+
+        // Step 2: Check if it's an element node
+        if (sourceNode.nodeType === Node.ELEMENT_NODE) {
+            // Step 3: Compare and update attributes
+            let sourceAttributes = sourceNode.attributes;
+            let targetAttributes = targetNode.attributes;
+            const targetAttrMap = new Map();
+            for (let i = 0; i < targetAttributes.length; i++) {
+                targetAttrMap.set(targetAttributes[i].name, targetAttributes[i].value);
+            }
+
+            // Update or add attributes from sourceNode to targetNode
+            for (let i = 0; i < sourceAttributes.length; i++) {
+                let attr = sourceAttributes[i];
+                if (targetAttrMap.get(attr.name) !== attr.value) {
+                    targetNode.setAttribute(attr.name, attr.value);
+                }
+                targetAttrMap.delete(attr.name); // Mark as processed
+            }
+
+            // Remove attributes that are in target but not in source
+            for (const attrName of targetAttrMap.keys()) {
+                targetNode.removeAttribute(attrName);
+            }
+
+            // Special handling for properties like value, checked, selected, disabled
+            if (sourceNode.value !== targetNode.value) {
+                targetNode.value = sourceNode.value;
+            }
+            if (sourceNode.checked !== targetNode.checked) {
+                targetNode.checked = sourceNode.checked;
+            }
+             if (sourceNode.selected !== targetNode.selected) {
+                targetNode.selected = sourceNode.selected;
+            }
+            if (sourceNode.disabled !== targetNode.disabled) {
+                targetNode.disabled = sourceNode.disabled;
+            }
+
+
+            // Step 4: Recursively compare and update children
+            let sourceChildren = sourceNode.childNodes;
+            let targetChildren = targetNode.childNodes;
+            let maxLen = Math.max(sourceChildren.length, targetChildren.length);
+
+            for (let i = 0; i < maxLen; i++) {
+                if (i >= targetChildren.length) {
+                    // If the target has fewer children, append the new child
+                    if (sourceChildren[i]) { 
+                        targetNode.appendChild(sourceChildren[i].cloneNode(true));
+                    }
+                } else if (i >= sourceChildren.length) {
+                     // If the source has fewer children, remove extra target child
+                     targetNode.removeChild(targetChildren[i]);
+                } else {
+                    // Otherwise, update the existing child
+                    h.updateDOM(sourceChildren[i], targetChildren[i]);
+                }
+            }
+
+        } else if (sourceNode.nodeType === Node.TEXT_NODE) {
+            // Step 5: Update text content if the text nodes are different
+            if (sourceNode.nodeValue !== targetNode.nodeValue) {
+                targetNode.nodeValue = sourceNode.nodeValue;
+            }
+        }
+        // Other node types (comments, etc.) are ignored for updates in this version
+    },
+    safeEscape: (html, x) => {
+        if ( x )
+            console.log(x);
+
+        if (typeof html !== 'string') return html; // Return non-strings as-is
+
+        // Generated by Claude 3.5 Sonnet
+        const preserveTags = [
+            'pre',
+            'code',
+            'script',
+            'style',
+            'textarea',
+            'math',
+            'mi',
+            'mo',
+            'mn',
+            'ms',
+            'mtext',
+            'samp',
+            'kbd',
+            'var',
+            'svg',
+            'xmp'
+        ].join('|');
+
+        // Track whether we're inside a preserve tag
+        let isInPreserveTag = false;
+        let currentTag = '';
+
+        // Split the input into tokens that are either tags or text
+        // Improved regex to handle self-closing tags and attributes better
+        return html.split(/(<\/?(?:${preserveTags})(?:\s+[^>]*)?\/?>|<\/?[a-zA-Z][^>]*>)/i)
+            .filter(part => part) // Remove empty strings from split
+            .map(part => {
+                // Check if this part is a preserve tag
+                const preserveTagMatch = part.match(new RegExp(`^<(/?)(${preserveTags})([\\s>/])`, 'i'));
+
+                if (preserveTagMatch) {
+                    // Toggle the preserve state based on opening/closing tags
+                    if (!preserveTagMatch[1] && !part.endsWith('/>')) { // Opening tag, not self-closing
+                        isInPreserveTag = true;
+                        currentTag = preserveTagMatch[2];
+                    } else if (preserveTagMatch[1]) { // Closing tag
+                        // Only close if it matches the current open tag
+                        if (isInPreserveTag && currentTag.toLowerCase() === preserveTagMatch[2].toLowerCase()) {
+                             isInPreserveTag = false;
+                             currentTag = '';
+                        }
+                    }
+                    return part; // Return the tag itself unmodified
+                }
+
+                // If we're not in a preserve tag and this isn't an HTML tag, escape <
+                if (!isInPreserveTag && !part.startsWith('<')) {
+                    return part.replace(/</g, '&lt;');
+                }
+
+                // Return other tags or content within preserve tags unmodified
+                return part;
+            })
+            .join('');
+    },
+    
+    /**
+     * Injects CSS styles into the document head.
+     * @param {string} cssString - The CSS string to inject.
+     * @param {string} [id] - Optional ID for the style element to prevent duplicates.
+     * @returns {HTMLStyleElement} The created or existing style element.
+     */
+    injectStyles: (cssString, id) => {
+        // If an ID is provided, check if styles with this ID already exist
+        if (id) {
+            const existingStyle = document.getElementById(id);
+            if (existingStyle) {
+                // Styles already injected, return the existing element
+                return existingStyle;
+            }
+        }
+
+        // Create a new style element
+        const styleElement = document.createElement('style');
+        if (id) {
+            styleElement.id = id;
+        }
+        styleElement.textContent = cssString;
+
+        // Append to the document head
+        document.head.appendChild(styleElement);
+
+        return styleElement;
+    },
+
+    /**
+     * Calculates the distance between an element's edge and the viewport's corresponding edge
+     * @param {HTMLElement} elem - The element to measure from
+     * @param {"left"|"right"} edge - Which edge to measure from
+     * @returns {number} The distance in pixels
+     * @throws {Error} If invalid edge parameter is provided or element not found
+     */
+    getDistanceFromViewportEdge: (elem, edge = "right") => {
+        // Input validation
+        if (!elem || typeof elem.getBoundingClientRect !== 'function') {
+             throw new Error('Invalid element provided.');
+        }
+        if ( !["left", "right"].includes(edge) ) {
+            throw new Error('Edge parameter must be either "left" or "right"');
+        }
+
+        // Get the bounding rectangle of the elem
+        const rect = elem.getBoundingClientRect();
+
+        // Get the width of the viewport
+        const viewportWidth = window.innerWidth;
+
+        // Calculate distance based on specified edge
+        if (edge === "right") {
+            return viewportWidth - rect.right;
+        } else { // edge === "left"
+            return rect.left;
+        }
+    }
+};
+
+module.exports = { h };

package/src/GSToolBlockUtils.js

@@ -10,6 +10,8 @@
  */
 
 
+const GS_TOOL_BLOCK_TYPE = 'gs-tool';
+
 /**
  * Checks if a given code block content represents a GitSense Chat Tool Block.
  * It verifies if the first non-empty line starts with "# GitSense Chat Tool".
@@ -28,6 +30,65 @@ function isToolBlock(content) {
     return false;
 }
 
+
+// TODO: Add JSDocs
+function getToolBlocksByTool(content, tool, CodeBlockUtils) {
+    const { blocks, warnings } = CodeBlockUtils.extractCodeBlocks(content, { silent: true });
+
+    return blocks.filter((block, index) => {
+        if (block.type !== GS_TOOL_BLOCK_TYPE)
+            return;
+
+        try {
+            const data = parseToolBlock(block.content);
+
+            if (data.tool === tool) {
+                block.index = index;
+                return block;
+            }
+        } catch(error) {
+            // FIXME: We need a more elegant way to identify examples. 
+            if (!content.includes(/Internal INTEGER IDs/)) {
+                console.warn(`Invalid tool block JSON: ${error.message}`);
+            }
+        }
+    });
+}
+
+// TODO: Add JSDocs
+function getToolBlockElemsByTool(dom, tool) {
+    const elems = dom.querySelectorAll('pre');
+    const toolBockElems = [];
+
+    for ( let i = 0; i < elems.length; i++ ) {
+        const elem = elems[i];
+        let content = elem.textContent;
+
+        // We need to strip out the first two lines since this is not part of the actual code
+        // block. These two lines are designed to make it easy to identify the language 
+        content = content.split('\n').slice(2).join('\n');
+
+        if (!isToolBlock(content)) 
+            continue;
+
+        try {
+            const data = parseToolBlock(content, { silent: true });
+
+            if (data.tool === tool)
+                toolBockElems.push(elem);
+        } catch(error) {
+            // FIXME: We need a more elegant way to identify examples. 
+            if (!content.match(/Internal INTEGER IDs/)) {
+                console.warn("getToolBlockElemsByTool: ",error.message);
+            }
+            continue; 
+        }
+    }
+
+    return toolBockElems;
+}
+
+
 /**
  * Parses the content of a GitSense Chat Tool Block to extract the JSON payload.
  * It strips the marker line and any subsequent lines starting with '#' (comments)
@@ -136,7 +197,7 @@ function replaceToolBlock(markdownContent, toolName, newToolData, CodeBlockUtils
     // 2. Iterate through the processed blocks to find the target GitSense Chat Tool Block
     for (let i = 0; i < blocks.length; i++) {
         const block = blocks[i];
-        if (block.type === 'gs-tool' && block.toolData && block.toolData.tool === toolName) {
+        if (block.type === GS_TOOL_BLOCK_TYPE && block.toolData && block.toolData.tool === toolName) {
             targetBlockIndex = i;
             break; // Found the first matching tool block
         }
@@ -270,10 +331,14 @@ function detectAndFormatUnfencedToolBlock(messageContent) {
     };
 }
 
+
+
 module.exports = {
     isToolBlock,
     parseToolBlock,
     formatToolBlock,
     replaceToolBlock,
+    getToolBlocksByTool,
+    getToolBlockElemsByTool,
     detectAndFormatUnfencedToolBlock,
 }