@record-evolution/widget-markdown 1.0.4 → 1.0.5

package/package.json

@@ -3,7 +3,11 @@
     "description": "Webcomponent widget-markdown following open-wc recommendations",
     "license": "MIT",
     "author": "widget-markdown",
-    "version": "1.0.4",
+    "version": "1.0.5",
+    "engines": {
+        "node": ">=24.9.0",
+        "npm": ">=10.0.2"
+    },
     "type": "module",
     "main": "dist/widget-markdown.js",
     "types": "dist/src/widget-markdown.d.ts",

package/src/definition-schema.d.ts

@@ -6,15 +6,15 @@
  */
 
 /**
- * This is the label of the variable to be used in the replacement text like {{myLabel}}
+ * The variable name used in the markdown text. Reference this in your markdown using the {{label}} syntax. Use descriptive names like 'temperature', 'status', 'deviceName'.
  */
 export type Label = string;
 /**
- * This value will be shown in the output in place of {{myLabel}}
+ * The replacement text that will appear in place of {{label}} in the rendered output. Can be a static value or bound to a data column for dynamic updates.
  */
 export type Value = string;
 /**
- * A list of variables to replace in the text. To replace a variable in the markdown text use the label of the variable with this notation {{variable}}
+ * Array of variable definitions for dynamic text substitution. Each variable has a label (used in the markdown as {{label}}) and a value (the replacement text). Values can be static or bound to data columns for real-time updates.
  */
 export type Variables = {
   label?: Label;
@@ -22,11 +22,17 @@ export type Variables = {
   [k: string]: unknown;
 }[];
 
+/**
+ * A markdown rendering widget for displaying formatted text with dynamic variable substitution. Use this widget for documentation, instructions, dynamic reports, or any rich text content on dashboards. Supports full Markdown syntax including headers, lists, tables, links, and code blocks. Variables can be embedded using {{variableName}} notation and bound to data sources for real-time updates. Ideal for creating contextual help, status summaries, or narrative text that incorporates live data values.
+ */
 export interface InputData {
   markdown?: Markdown;
   data?: Variables;
   [k: string]: unknown;
 }
+/**
+ * The markdown-formatted text content to display. Supports all standard Markdown syntax: headers (#), bold (**text**), italic (*text*), lists (- item), links ([text](url)), code blocks (```), tables, and more. Use {{variableName}} to insert dynamic variables.
+ */
 export interface Markdown {
   [k: string]: unknown;
 }

package/src/definition-schema.json

@@ -1,15 +1,17 @@
 {
     "title": "InputData",
+    "description": "A markdown rendering widget for displaying formatted text with dynamic variable substitution. Use this widget for documentation, instructions, dynamic reports, or any rich text content on dashboards. Supports full Markdown syntax including headers, lists, tables, links, and code blocks. Variables can be embedded using {{variableName}} notation and bound to data sources for real-time updates. Ideal for creating contextual help, status summaries, or narrative text that incorporates live data values.",
     "type": "object",
     "properties": {
         "markdown": {
             "title": "Markdown",
+            "description": "The markdown-formatted text content to display. Supports all standard Markdown syntax: headers (#), bold (**text**), italic (*text*), lists (- item), links ([text](url)), code blocks (```), tables, and more. Use {{variableName}} to insert dynamic variables.",
             "order": 1,
             "type": "textarea"
         },
         "data": {
             "title": "Variables",
-            "description": "A list of variables to replace in the text. To replace a variable in the markdown text use the label of the variable with this notation {{variable}}",
+            "description": "Array of variable definitions for dynamic text substitution. Each variable has a label (used in the markdown as {{label}}) and a value (the replacement text). Values can be static or bound to data columns for real-time updates.",
             "type": "array",
             "order": 2,
             "items": {
@@ -17,13 +19,13 @@
                 "properties": {
                     "label": {
                         "title": "Label",
-                        "description": "This is the label of the variable to be used in the replacement text like {{myLabel}}",
+                        "description": "The variable name used in the markdown text. Reference this in your markdown using the {{label}} syntax. Use descriptive names like 'temperature', 'status', 'deviceName'.",
                         "type": "string",
                         "order": 1
                     },
                     "value": {
                         "title": "Value",
-                        "description": "This value will be shown in the output in place of {{myLabel}}",
+                        "description": "The replacement text that will appear in place of {{label}} in the rendered output. Can be a static value or bound to a data column for dynamic updates.",
                         "type": "string",
                         "order": 2
                     }

package/src/widget-markdown.ts

@@ -45,6 +45,8 @@ export class WidgetMarkdown extends LitElement {
     @state() private themeBgColor?: string
     @state() private themeTitleColor?: string
     @state() private themeSubtitleColor?: string
+    @state() private cachedHtmlTemplate?: string
+    @state() private lastMarkdown?: string
 
     version: string = 'versionplaceholder'
     marked: Marked
@@ -92,33 +94,47 @@ export class WidgetMarkdown extends LitElement {
     }
 
     /**
-     * Interpolates variables from inputData into the markdown text.
-     * Replaces patterns like {{variableName}} with corresponding values from inputData.
+     * Converts {{variableName}} to spans with data attributes for efficient updating.
+     * Markdown is parsed once, then only variable spans are updated.
      */
-    interpolateVariables(text: string): string {
-        if (!this.inputData) return text
-
+    convertVariablesToSpans(text: string): string {
         return text.replace(/\{\{([^}]+)\}\}/g, (match, varName) => {
             const key = varName.trim()
-            const dataItem = this.inputData?.data?.find((item) => item.label === key)
-            const value = dataItem?.value
-
-            // If variable doesn't exist, return the original placeholder
-            if (value === null || value === undefined) {
-                return match
-            } else if (typeof value === 'object') {
-                // For objects/arrays, return JSON representation
-                try {
-                    return JSON.stringify(value)
-                } catch {
-                    return match
-                }
-            } else {
-                return String(value)
-            }
+            return `<span class="md-var" data-var="${key}"></span>`
         })
     }
 
+    /**
+     * Updates variable spans in the rendered DOM without recreating the entire structure.
+     */
+    protected updated(changedProperties: PropertyValues): void {
+        super.updated(changedProperties)
+
+        if (changedProperties.has('inputData')) {
+            // Update only the variable spans
+            const varSpans = this.shadowRoot?.querySelectorAll('.md-var')
+            varSpans?.forEach((span) => {
+                const varName = span.getAttribute('data-var')
+                if (varName) {
+                    const dataItem = this.inputData?.data?.find((item) => item.label === varName)
+                    const value = dataItem?.value
+
+                    if (value === null || value === undefined) {
+                        span.textContent = `{{${varName}}}`
+                    } else if (typeof value === 'object') {
+                        try {
+                            span.textContent = JSON.stringify(value)
+                        } catch {
+                            span.textContent = `{{${varName}}}`
+                        }
+                    } else {
+                        span.textContent = String(value)
+                    }
+                }
+            })
+        }
+    }
+
     static styles = [
         unsafeCSS(githubCss),
         unsafeCSS(highlightCSS),
@@ -172,12 +188,18 @@ export class WidgetMarkdown extends LitElement {
 
     render() {
         const mdText: string = String(this.inputData?.markdown ?? '')
-        const interpolatedText: string = this.interpolateVariables(mdText)
-        const mdHtml: string = this.marked.parse(interpolatedText) as string
+
+        // Only re-parse markdown if the markdown text actually changed
+        if (mdText !== this.lastMarkdown) {
+            this.lastMarkdown = mdText
+            const textWithSpans: string = this.convertVariablesToSpans(mdText)
+            this.cachedHtmlTemplate = this.marked.parse(textWithSpans) as string
+        }
+
         return html`
             <div class="wrapper" style="background-color: ${this.themeBgColor}">
                 <div class="paging markdown-body" ?active=${this.inputData?.markdown}>
-                    ${unsafeHTML(mdHtml)}
+                    ${unsafeHTML(this.cachedHtmlTemplate ?? '')}
                 </div>
             </div>
         `