From 8ac3b3c514518dca608943cbbb138d78cd983e75 Mon Sep 17 00:00:00 2001
From: Michael Geers <michael@geers.tv>
Date: Sun, 1 Sep 2024 11:32:14 +0200
Subject: [PATCH] Config UI: add markdown description (#15817)

---
 assets/js/components/Config/Markdown.vue     | 19 +++++++++++++++++++
 assets/js/components/Config/MeterModal.vue   |  6 ++++++
 assets/js/components/Config/VehicleModal.vue | 12 +++++++++++-
 package-lock.json                            |  7 +++++++
 package.json                                 |  1 +
 util/templates/types.go                      | 15 ++++++++++++++-
 6 files changed, 58 insertions(+), 2 deletions(-)
 create mode 100644 assets/js/components/Config/Markdown.vue

diff --git a/assets/js/components/Config/Markdown.vue b/assets/js/components/Config/Markdown.vue
new file mode 100644
index 000000000..33cdfe202
--- /dev/null
+++ b/assets/js/components/Config/Markdown.vue
@@ -0,0 +1,19 @@
+<template>
+	<div v-html="compiledMarkdown"></div>
+</template>
+
+<script>
+import snarkdown from "snarkdown";
+
+export default {
+	name: "MarkdownRenderer",
+	props: {
+		markdown: String,
+	},
+	computed: {
+		compiledMarkdown() {
+			return snarkdown(this.markdown);
+		},
+	},
+};
+</script>
diff --git a/assets/js/components/Config/MeterModal.vue b/assets/js/components/Config/MeterModal.vue
index cd50ddaad..74257bd2e 100644
--- a/assets/js/components/Config/MeterModal.vue
+++ b/assets/js/components/Config/MeterModal.vue
@@ -65,6 +65,7 @@
 								</select>
 							</FormRow>
 							<p v-if="loadingTemplate">Loading ...</p>
+							<Markdown v-if="description" :markdown="description" class="my-4" />
 							<Modbus
 								v-if="modbus"
 								v-model:modbus="values.modbus"
@@ -164,6 +165,7 @@ import api from "../../api";
 import test from "./mixins/test";
 import AddDeviceButton from "./AddDeviceButton.vue";
 import Modbus from "./Modbus.vue";
+import Markdown from "./Markdown.vue";
 
 const initialValues = { type: "template" };
 
@@ -182,6 +184,7 @@ export default {
 		TestResult,
 		AddDeviceButton,
 		PropertyCollapsible,
+		Markdown,
 	},
 	mixins: [test],
 	props: {
@@ -255,6 +258,9 @@ export default {
 				port: Port,
 			};
 		},
+		description() {
+			return this.template?.Requirements?.Description;
+		},
 		apiData() {
 			return {
 				template: this.templateName,
diff --git a/assets/js/components/Config/VehicleModal.vue b/assets/js/components/Config/VehicleModal.vue
index 8de376eff..342916d3d 100644
--- a/assets/js/components/Config/VehicleModal.vue
+++ b/assets/js/components/Config/VehicleModal.vue
@@ -66,7 +66,8 @@
 									</optgroup>
 								</select>
 							</FormRow>
-
+							<p v-if="loadingTemplate">Loading ...</p>
+							<Markdown v-if="description" :markdown="description" class="my-4" />
 							<PropertyEntry
 								v-for="param in normalParams"
 								:key="param.Name"
@@ -261,6 +262,7 @@ import TestResult from "./TestResult.vue";
 import SelectGroup from "../SelectGroup.vue";
 import PropertyEntry from "./PropertyEntry.vue";
 import PropertyCollapsible from "./PropertyCollapsible.vue";
+import Markdown from "./Markdown.vue";
 import api from "../../api";
 import test from "./mixins/test";
 
@@ -281,6 +283,7 @@ export default {
 		SelectGroup,
 		PropertyCollapsible,
 		PropertyEntry,
+		Markdown,
 	},
 	mixins: [test],
 	props: {
@@ -296,6 +299,7 @@ export default {
 			templateName: null,
 			template: null,
 			values: { ...initialValues },
+			loadingTemplate: false,
 		};
 	},
 	computed: {
@@ -323,6 +327,9 @@ export default {
 		advancedParams() {
 			return this.templateParams.filter((p) => p.Advanced);
 		},
+		description() {
+			return this.template?.Requirements?.Description;
+		},
 		apiData() {
 			const data = {
 				template: this.templateName,
@@ -402,6 +409,7 @@ export default {
 		},
 		async loadTemplate() {
 			this.template = null;
+			this.loadingTemplate = true;
 			try {
 				const opts = {
 					params: {
@@ -414,6 +422,7 @@ export default {
 			} catch (e) {
 				console.error(e);
 			}
+			this.loadingTemplate = false;
 		},
 		applyDefaultsFromTemplate() {
 			const params = this.template?.Params || [];
@@ -496,3 +505,4 @@ export default {
 	padding-right: 0;
 }
 </style>
+import type MarkdownVue from "./Markdown.vue";
diff --git a/package-lock.json b/package-lock.json
index 701e9c1cf..8e8bbb6bd 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -40,6 +40,7 @@
         "prettier-plugin-toml": "^2.0.1",
         "rollup-plugin-visualizer": "^5.8.3",
         "smoothscroll-polyfill": "^0.4.4",
+        "snarkdown": "^2.0.0",
         "typescript": "^5.2.2",
         "vite": "^5.1.1",
         "vite-plugin-toml": "^0.7.0",
@@ -8795,6 +8796,12 @@
         "tslib": "^2.0.3"
       }
     },
+    "node_modules/snarkdown": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/snarkdown/-/snarkdown-2.0.0.tgz",
+      "integrity": "sha512-MgL/7k/AZdXCTJiNgrO7chgDqaB9FGM/1Tvlcenenb7div6obaDATzs16JhFyHHBGodHT3B7RzRc5qk8pFhg3A==",
+      "license": "MIT"
+    },
     "node_modules/source-map": {
       "version": "0.6.1",
       "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz",
diff --git a/package.json b/package.json
index ec60fb586..b04865dda 100644
--- a/package.json
+++ b/package.json
@@ -47,6 +47,7 @@
     "prettier-plugin-toml": "^2.0.1",
     "rollup-plugin-visualizer": "^5.8.3",
     "smoothscroll-polyfill": "^0.4.4",
+    "snarkdown": "^2.0.0",
     "typescript": "^5.2.2",
     "vite": "^5.1.1",
     "vite-plugin-toml": "^0.7.0",
diff --git a/util/templates/types.go b/util/templates/types.go
index c95838f58..b6e597b4b 100644
--- a/util/templates/types.go
+++ b/util/templates/types.go
@@ -131,6 +131,19 @@ func (t *TextLanguage) MarshalJSON() (out []byte, err error) {
 	return json.Marshal(s)
 }
 
+func (r Requirements) MarshalJSON() ([]byte, error) {
+	mu.Lock()
+	custom := struct {
+		EVCC        []string `json:",omitempty"`
+		Description string   `json:",omitempty"`
+	}{
+		EVCC:        r.EVCC,
+		Description: r.Description.String(encoderLanguage),
+	}
+	mu.Unlock()
+	return json.Marshal(custom)
+}
+
 // Requirements
 type Requirements struct {
 	EVCC        []string     // EVCC requirements, e.g. sponsorship
@@ -247,7 +260,7 @@ type TemplateDefinition struct {
 	Covers       []string         `json:",omitempty"` // list of covered outdated template names
 	Products     []Product        `json:",omitempty"` // list of products this template is compatible with
 	Capabilities []string         `json:",omitempty"`
-	Requirements Requirements     `json:"-"`
+	Requirements Requirements     `json:",omitempty"`
 	Linked       []LinkedTemplate `json:",omitempty"` // a list of templates that should be processed as part of the guided setup
 	Params       []Param          `json:",omitempty"`
 	Render       string           `json:"-"` // rendering template