From 2ee3d718e069abbfad14621fda2db30fd4081438 Mon Sep 17 00:00:00 2001
From: Taron Chatoyan <47221390+t-chatoyan@users.noreply.github.com>
Date: Fri, 7 Jun 2024 03:31:59 +0400
Subject: [PATCH] feat(plugins): doc is now generated based on JSON-SCHEMA
 (#36)

Co-authored-by: brian.mulier <bmmulier@hotmail.fr>
---
 package-lock.json                       |  16 ++
 package.json                            |   1 +
 src/components/index.js                 |   6 +-
 src/components/plugins/SchemaToCode.vue | 166 +++++++++++++
 src/components/plugins/SchemaToHtml.vue | 304 ++++++++++++++++++++++++
 5 files changed, 492 insertions(+), 1 deletion(-)
 create mode 100644 src/components/plugins/SchemaToCode.vue
 create mode 100644 src/components/plugins/SchemaToHtml.vue

diff --git a/package-lock.json b/package-lock.json
index d7ead42..d038e84 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -13,6 +13,7 @@
         "eslint": "^8.57.0",
         "eslint-plugin-vue": "^9.23.0",
         "sass": "^1.71.1",
+        "shiki": "^1.1.7",
         "vite": "^5.1.6",
         "vite-plugin-static-copy": "^1.0.1"
       },
@@ -775,6 +776,12 @@
         "win32"
       ]
     },
+    "node_modules/@shikijs/core": {
+      "version": "1.5.2",
+      "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-1.5.2.tgz",
+      "integrity": "sha512-wSAOgaz48GmhILFElMCeQypSZmj6Ru6DttOOtl3KNkdJ17ApQuGNCfzpk4cClasVrnIu45++2DBwG4LNMQAfaA==",
+      "dev": true
+    },
     "node_modules/@types/estree": {
       "version": "1.0.5",
       "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.5.tgz",
@@ -2773,6 +2780,15 @@
         "node": ">=8"
       }
     },
+    "node_modules/shiki": {
+      "version": "1.5.2",
+      "resolved": "https://registry.npmjs.org/shiki/-/shiki-1.5.2.tgz",
+      "integrity": "sha512-fpPbuSaatinmdGijE7VYUD3hxLozR3ZZ+iAx8Iy2X6REmJGyF5hQl94SgmiUNTospq346nXUVZx0035dyGvIVw==",
+      "dev": true,
+      "dependencies": {
+        "@shikijs/core": "1.5.2"
+      }
+    },
     "node_modules/slash": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz",
diff --git a/package.json b/package.json
index 1fca7f4..162a763 100644
--- a/package.json
+++ b/package.json
@@ -37,6 +37,7 @@
     "eslint": "^8.57.0",
     "eslint-plugin-vue": "^9.23.0",
     "sass": "^1.71.1",
+    "shiki": "^1.1.7",
     "vite": "^5.1.6",
     "vite-plugin-static-copy": "^1.0.1"
   }
diff --git a/src/components/index.js b/src/components/index.js
index aaf201c..684d730 100644
--- a/src/components/index.js
+++ b/src/components/index.js
@@ -19,7 +19,11 @@ import TaskIcon from "./misc/TaskIcon.vue";
 // buttons
 import AddTaskButton from "./buttons/AddTaskButton.vue";
 
+// plugins
+import SchemaToHtml from "./plugins/SchemaToHtml.vue";
+
 export {ClusterNode, DotNode, EdgeNode, TaskNode, TriggerNode, BasicNode, CollapsedClusterNode, DependenciesNode};
 export {Topology}
 export {ExecutionInformations, State, TaskIcon};
-export {AddTaskButton};
\ No newline at end of file
+export {AddTaskButton};
+export {SchemaToHtml};
\ No newline at end of file
diff --git a/src/components/plugins/SchemaToCode.vue b/src/components/plugins/SchemaToCode.vue
new file mode 100644
index 0000000..8fdd4bb
--- /dev/null
+++ b/src/components/plugins/SchemaToCode.vue
@@ -0,0 +1,166 @@
+<template>
+    <div class="code-block mb-3" @mouseover="hoverCode" @mouseleave="isHoveringCode = false">
+        <div class="language" v-if="language">{{ language }}</div>
+        <template v-if="isHoveringCode">
+            <button ref="copyButton" class="copy">
+                <component
+                  :is="copyIcon"
+                  @click="copyToClipboard"
+                />
+            </button>
+            <div ref="copyTooltip" v-if="!!copyIconResetTimer" id="copied-tooltip" role="tooltip">
+                Copied!
+                <div id="arrow" data-popper-arrow></div>
+            </div>
+        </template>
+        <div v-html="codeData" />
+    </div>
+</template>
+
+<script>
+    import { createPopper } from "@popperjs/core";
+    import { codeToHtml } from 'shiki';
+    import ContentCopy from "vue-material-design-icons/ContentCopy.vue";
+    import Check from "vue-material-design-icons/Check.vue";
+    import {defineComponent} from "vue";
+
+    export default defineComponent({
+        props: {
+            code: {
+                type: String,
+                default: ""
+            },
+            language: {
+                type: String,
+                default: null
+            },
+            filename: {
+                type: String,
+                default: null
+            },
+            highlights: {
+                type: Array,
+                default: () => []
+            },
+            meta: {
+                type: String,
+                default: null
+            }
+        },
+        data() {
+            return {
+                icons: shallowRef({
+                    ContentCopy: shallowRef(ContentCopy),
+                    Check: shallowRef(Check)
+                }),
+                copyIcon: undefined,
+                copyIconResetTimer: undefined,
+                isHoveringCode: false,
+                codeData: null,
+            }
+        },
+       async created() {
+            this.copyIcon = this.icons.ContentCopy;
+            this.codeData = await codeToHtml(this.code, {
+              lang: this.language,
+              theme: 'github-dark',
+            });
+        },
+        methods: {
+            hoverCode(){
+                this.isHoveringCode = true;
+                if(this.copyIconResetTimer) {
+                    nextTick(() => {
+                        createPopper(this.$refs.copyButton, this.$refs.copyTooltip, {
+                            placement: 'left',
+                        });
+                    });
+                }
+            },
+            copyToClipboard() {
+                clearTimeout(this.copyIconResetTimer);
+
+                navigator.clipboard.writeText(this.code.trimEnd())
+
+                this.copyIcon = this.icons.Check;
+
+                this.copyIconResetTimer = setTimeout(() => {
+                    this.copyIcon = this.icons.ContentCopy;
+                    this.copyIconResetTimer = undefined;
+                }, 2000)
+            },
+        },
+    });
+</script>
+
+<style lang="scss" scoped>
+    .code-block {
+        background-color: #161617;
+        border: 1px solid #252526;
+        padding: 1.25rem 1.5rem;
+        border-radius: var(--bs-border-radius-lg);
+        color: var(--bs-white);
+        position: relative;
+
+        .language {
+            position: absolute;
+            right: 0.35rem;
+            top: 0.25rem;
+            color: var(--bs-gray-600);
+            font-size: 0.75rem;
+        }
+
+        :deep(pre) {
+            margin-bottom: 0;
+        }
+
+        :deep(.github-dark) {
+            background-color: transparent !important;
+            code {
+                display: flex;
+                flex-direction: column;
+            }
+        }
+
+        .copy {
+            position: absolute;
+            right: 0;
+            bottom: 0.1rem;
+            color: #7081b9;
+            border: none;
+            background: none;
+        }
+
+        #copied-tooltip {
+            border-radius: .25rem;
+            background: #8997bd;
+            padding: 4px 8px;
+            font-size: 0.75rem;
+            margin-right: 0.2rem !important;
+
+            #arrow,
+            #arrow::before {
+                position: absolute;
+                width: 8px;
+                height: 8px;
+                background: inherit;
+            }
+
+            #arrow {
+                visibility: hidden;
+                right: -4px;
+            }
+
+            #arrow::before {
+                visibility: visible;
+                content: '';
+                transform: rotate(45deg);
+            }
+        }
+    }
+
+    :deep(pre code .line) {
+        display: block;
+        min-height: 1rem;
+    }
+</style>
diff --git a/src/components/plugins/SchemaToHtml.vue b/src/components/plugins/SchemaToHtml.vue
new file mode 100644
index 0000000..39ccc0d
--- /dev/null
+++ b/src/components/plugins/SchemaToHtml.vue
@@ -0,0 +1,304 @@
+<template>
+    <div class="bd-markdown">
+        <div class="doc-alert alert alert-warning" role="alert" v-if="page.deprecated">
+            <p>⚠ Deprecated</p>
+        </div>
+
+        <SchemaToCode language="yaml" :code='`type: "${getPageName()}"`'/>
+        <p v-if="page.title">
+            <span style="font-size:1.5em;" v-html="replaceText(page.title)"/>
+        </p>
+        <slot :content="page.description" name="markdown" />
+        <h2 id="examples" v-if="page.body.children['examples']">
+            <a href="#examples">Examples</a>
+        </h2>
+        <template v-for="example in page.body.children['examples']"
+                  v-if="page.body.children['examples']">
+            <slot :content="example.title" name="markdown" />
+            <SchemaToCode :language="example.lang" :code="generateExampleCode(example)" v-if="example.code" />
+        </template>
+        <template v-for="(pageBlock, key) in page.body.children" v-if="page.body.children">
+            <template v-if="key !== 'examples'">
+                <h2 :id="key">
+                    <a :href="`#${key}`">{{capitalizeFirstLetter(key)}}</a>
+                </h2>
+                <template v-for="(property, propertyKey) in sortSchemaByRequired(pageBlock)" v-if="key !== 'definitions'">
+                    <h3 :id="property.name || propertyKey">
+                        <a :href="`#${property.name || propertyKey}`">
+                            <code>{{property.name || propertyKey}}</code>
+                        </a>
+                    </h3>
+                    <div class="doc-alert alert alert-warning" role="alert"
+                         v-if="property['$deprecated']">
+                        <p>⚠ Deprecated</p>
+                    </div>
+                    <ul>
+                        <li><strong>Type: </strong>
+                            <mark class="type-mark type-mark-default"
+                                  v-if="property.type || property['$ref']">
+                                {{property.type || property['$ref']?.split('.').reverse()[0]}}
+                            </mark>
+                            <ul v-else-if="property.anyOf">
+                                <li v-for="anyOf in property.anyOf">
+                                    <mark class="type-mark type-mark-default">{{anyOf.type}}</mark>
+                                </li>
+                            </ul>
+                        </li>
+                        <li v-if="property.items">
+                            <strong>SubType: </strong>
+                            <a aria-current="page"
+                               :href="generateTaskHref(property.items['$ref'])"
+                               class="router-link-active router-link-exact-active">
+                                <mark class="type-mark type-mark-default">
+                                    {{property.items['$ref']?.split('.').reverse()[0] ||
+                                    property.items.type ||'String'}}
+                                </mark>
+                            </a>
+                        </li>
+                        <li v-if="property['$dynamic'] !== undefined"><strong>Dynamic: </strong>{{
+                            property['$dynamic'] === true ? "✔️" :
+                            (property['$dynamic'] === false ? "❌" : "❓") }}
+                        </li>
+                        <li v-if="property['$required'] !== undefined"><strong>Required: </strong> {{
+                            property['$required'] === true ? "✔️" :
+                            (property['$required'] === false ? "❌" : "❓") }}
+                        </li>
+                        <li v-if="property.default !== undefined">
+                            <strong>Default: </strong>
+                            <code>{{property.default}}</code>
+                        </li>
+                        <li v-if="property.format">
+                            <strong>Format: </strong>
+                            <code> {{property.format}} </code>
+                        </li>
+                        <li v-if="property.minItems">
+                            <strong>Min items: </strong>
+                            <code> {{property.minItems}} </code>
+                        </li>
+                        <li v-if="property.minLength">
+                            <strong>Min length: </strong>
+                            <code>{{property.minLength}}</code>
+                        </li>
+                        <li v-if="property.enum">
+                            <strong>Possible Values:</strong>
+                            <ul>
+                                <li v-for="possibleValue in property.enum">
+                                    <code data-v-c4861ad0="" class="">{{possibleValue}}</code>
+                                </li>
+                            </ul>
+                        </li>
+                    </ul>
+
+                    <slot :content="property.title" name="markdown" />
+                    <blockquote class="blockquote">
+                        <slot :content="property.description" name="markdown" />
+                    </blockquote>
+                </template>
+                <template v-else>
+                    <template v-for="(item, key) in pageBlock"
+                              v-if="pageBlock">
+                        <h3 :id="key">
+                            <a :href="`#${key}`">
+                                <code>{{key}}</code>
+                            </a>
+                        </h3>
+                        <h4 id="properties-1"
+                            v-if="item.properties">
+                            <a href="#properties-1">Properties</a>
+                        </h4>
+                        <template
+                          v-for="(definition, key) in item.properties"
+                          v-if="item.properties">
+                            <h5 :id="definition.name || key">
+                                <a :href="`#${definition.name || key}`">
+                                    <code>{{definition.name || key}}</code>
+                                </a>
+                            </h5>
+                            <ul>
+                                <li><strong>Type: </strong>
+                                    <mark class="type-mark type-mark-default">
+                                        {{definition.type ||
+                                        definition['$ref']?.split('.').reverse()[0]}}
+                                    </mark>
+                                </li>
+                                <li v-if="definition.items">
+                                    <strong>SubType: </strong>
+                                    <a aria-current="page"
+                                       :href="generateTaskHref(definition.items['$ref'])"
+                                       class="router-link-active router-link-exact-active">
+                                        <mark class="type-mark type-mark-default">
+                                            {{definition.items?.type || 'Task'}}
+                                        </mark>
+                                    </a>
+                                </li>
+                                <li v-if="definition['$dynamic'] !== undefined">
+                                    <strong>Dynamic: </strong>
+                                    {{definition['$dynamic'] === true ? "✔️" :
+                                    (definition['$dynamic'] === false ? "❌" : "❓") }}
+                                </li>
+                                <li v-if="definition['$required'] !== undefined">
+                                    <strong>Required: </strong>
+                                    {{
+                                    definition['$required'] === true ? "✔️" :
+                                    (definition['$required'] === false ? "❌" : "❓") }}
+                                </li>
+                                <li v-if="definition.default !== undefined">
+                                    <strong>Default: </strong>
+                                    <code>{{definition.default}}</code>
+                                </li>
+                                <li v-if="definition.format">
+                                    <strong>Format: </strong>
+                                    <code>{{definition.format}}</code>
+                                </li>
+                                <li v-if="definition.minItems">
+                                    <strong>Min items: </strong>
+                                    <code>{{definition.minItems}}</code>
+                                </li>
+                            </ul>
+                            <p>
+                                <strong v-html="replaceText(definition.title)"/>
+                            </p>
+                            <blockquote class="blockquote">
+                                <p v-html="replaceText(definition.description)"/>
+                            </blockquote>
+                        </template>
+                    </template>
+                </template>
+            </template>
+        </template>
+    </div>
+</template>
+
+<script setup>
+    import SchemaToCode from "./SchemaToCode.vue";
+
+    const props = defineProps({
+        page: {
+            type: Object,
+            required: true,
+        },
+        getPageName: {
+            type: Function,
+            required: true,
+        }
+    });
+
+
+    function capitalizeFirstLetter(str) {
+        return str.charAt(0).toUpperCase() + str.slice(1);
+    }
+
+    const replaceText = (str) => {
+        str = str?.split("```")[0]?.replace(/`([^`]*)`/g, '<code>$1</code>');
+        str = str?.replace(
+          /\[(.*?)\]\((.*?)\)/g,
+          (match, text, url) => {
+              if (text && url ) {
+                  return `<a href="${url}" rel="nofollow" target="_blank">${text}</a>`;
+              } else {
+                  return match;
+              }
+          }
+        );
+        return str?.split("```")[0];
+    };
+
+    const generateTaskHref = (href) => {
+        if (href) {
+            const taskHref = href?.split('/');
+            return `#${taskHref[taskHref?.length - 1].toLowerCase()}`;
+        }
+    };
+
+    const generateDescHtml = computed(() => {
+        const textBlocks = props.page?.description.split('\n\n');
+        let content = '';
+        textBlocks.forEach((text) => {
+            const newText = replaceText(text);
+            const descriptionParts = newText?.split(/:\s?\n/);
+
+            if (descriptionParts) {
+                const alertParts = descriptionParts[0].split(/::alert{type=\"warning\"}\n/);
+                const alertContent =  (alertParts.length > 1)
+                ?
+                    `<div class="doc-alert alert alert-warning" role="alert">
+                      <p>${replaceText(alertParts[1]?.split(':')[0])}</p>
+                    </div>`
+                :
+                    `<p>${descriptionParts[0]}:</p>`;
+
+                const listContent = descriptionParts[1]
+                ?
+                    `<ul>${generateList(descriptionParts[1])}</ul>`
+                :
+                    '';
+
+                content += alertContent + listContent;
+            } else {
+                content += `<p>${newText}</p>`;
+            }
+        });
+
+        return content;
+    });
+
+    const sortSchemaByRequired = (schema) => {
+        const requiredKeys = [];
+        const nonRequiredKeys = [];
+
+        for (const key in schema) {
+            if (schema[key].$required) {
+                requiredKeys.push(key);
+            } else {
+                nonRequiredKeys.push(key);
+            }
+        }
+
+        const sortedKeys = [...requiredKeys, ...nonRequiredKeys];
+
+        const sortedSchema = {};
+        sortedKeys.forEach(key => {
+            sortedSchema[key] = schema[key];
+        });
+
+        return sortedSchema;
+    }
+
+    const generateList = (descriptionPart) => {
+        let optionList = '';
+        descriptionPart?.split(/[-*]/).forEach((item) => {
+            if (item.trim()) {
+                optionList += `
+                  <li>${replaceText(item)}</li>
+                `
+            }
+        });
+
+        return optionList;
+    }
+
+    const generateExampleCode = (example) => {
+        if (!example?.full) {
+            const firstCode = `id: "${props.getPageName()?.split('.').reverse()[0]?.toLowerCase()}"\ntype: "${props.getPageName()}"\n`;
+            return firstCode.concat(example.code)
+        }
+
+        return example.code;
+    }
+</script>
+
+<style lang="scss" scoped>
+    :deep(.bd-markdown) {
+        p {
+            strong {
+                code{
+                    background: #161617;
+                    border: 1px solid #252526;
+                    border-radius: var(--bs-border-radius);
+                    color: #b9b9ba;
+                    padding: 0 .25rem;
+                }
+            }
+        }
+    }
+</style>
\ No newline at end of file