feat: json-schema-based plugin doc (#174)

---------

Co-authored-by: YannC <[email protected]>

package.json

@@ -18,7 +18,6 @@
       "require": "./dist/kestra-ui.umd.cjs"
     },
     "./style.css": "./dist/kestra-ui.css",
-    "./scss/*": "./src/scss/*",
     "./src/*": "./src/*"
   },
   "scripts": {
@@ -45,6 +44,7 @@
     "moment-timezone": "^0.5.46",
     "vue": "^3.5.5",
     "vue-material-design-icons": "^5.3.0",
+    "vue-router": "^4.5.0",
     "vuex": "^4.1.0",
     "yaml": "^2.5.1"
   },
@@ -80,7 +80,7 @@
     "@nuxtjs/mdc": "^0.12.1",
     "@popperjs/core": "^2.11.8",
     "mermaid": "^11.4.1",
-    "shiki": "^1.26.1",
+    "shiki": "^1.22.0",
     "vue-i18n": "^11.0.1"
   },
   "optionalDependencies": {

src/components/misc/Collapsible.vue

@@ -0,0 +1,68 @@
+<template>
+    <div :id="href" class="d-flex flex-column gap-2">
+        <button @click="collapsed = !collapsed" class="d-flex align-items-center justify-content-between fw-bold gap-2 collapse-button" :class="{collapsed}" data-toggle="collapse" :data-target="'#' + href + '-body'" aria-expanded="false" :aria-controls="href + '-body'">
+            <span class="d-flex gap-2 align-items-center"><component v-if="arrow" class="arrow" :is="collapsed ? MenuRight : MenuDown" />{{ clickableText }}<slot name="additionalButtonText" /></span>
+            <span v-if="$slots.buttonRight" class="d-flex flex-grow-1">
+                <slot name="buttonRight" :collapsed="collapsed" />
+            </span>
+        </button>
+        <div v-if="$slots.content" v-show="!collapsed" :id="href + '-body'" class="collapsible-body">
+            <slot name="content" />
+        </div>
+    </div>
+</template>
+
+<script setup lang="ts">
+    import {ref, watch} from "vue";
+    import MenuRight from "vue-material-design-icons/MenuRight.vue";
+    import MenuDown from "vue-material-design-icons/MenuDown.vue";
+    import {useRoute} from "vue-router";
+
+    const props = withDefaults(defineProps<{ href?: string, clickableText: string, arrow: boolean, initiallyExpanded: boolean }>(), {
+        href: Math.random().toString(36).substring(2, 5),
+        arrow: true,
+        initiallyExpanded: false
+    });
+
+    const collapsed = ref(!props.initiallyExpanded);
+
+    const route = useRoute();
+
+    const emit = defineEmits(["expand"]);
+
+    watch(
+        () => {
+            return route.hash;
+        },
+        routeHash => {
+            if (routeHash === "#" + props.href) {
+                collapsed.value = false;
+                emit("expand");
+            }
+        },
+        {immediate: true}
+    );
+
+    watch(
+        () => props.initiallyExpanded,
+        initiallyExpanded => {
+            if (initiallyExpanded) {
+                collapsed.value = !initiallyExpanded;
+            }
+        },
+        {immediate: true}
+    );
+</script>
+
+<style scoped lang="scss">
+    .collapse-button {
+        padding: 0;
+        border: none;
+        background: none;
+
+        &:focus {
+            outline:none;
+            box-shadow: none;
+        }
+    }
+</style>

src/components/plugins/CollapsibleProperties.vue

@@ -0,0 +1,145 @@
+<template>
+    <Collapsible :clickable-text="sectionName" :href="href" @expand="emit('expand')" :initially-expanded="initiallyExpanded">
+        <template v-if="Object.keys(properties ?? {}).length > 0" #content>
+            <div class="border rounded">
+                <Collapsible
+                    class="property p-3"
+                    v-for="(property, propertyKey) in sortSchemaByRequired(properties)"
+                    :key="propertyKey"
+                    :arrow="false"
+                    :clickable-text="propertyKey"
+                    :href="href + '_' + propertyKey"
+                    @expand="initiallyExpanded = true"
+                >
+                    <template #additionalButtonText>
+                        <span v-if="property['$required']" class="text-danger"> *</span>
+                    </template>
+                    <template #buttonRight="{collapsed}">
+                        <span class="d-flex flex-grow-1 align-items-center justify-content-between">
+                            <span class="d-flex gap-1">
+                                <Tooltip v-if="showDynamic && !isDynamic(property)" class="d-flex" title="Non-dynamic">
+                                    <Cancel class="text-danger" />
+                                </Tooltip>
+                                <Tooltip v-if="property['$beta']" class="d-flex" title="Beta">
+                                    <AlphaBBox class="text-warning" />
+                                </Tooltip>
+                                <Tooltip v-if="property['$deprecated']" class="d-flex" title="Deprecated">
+                                    <Alert class="text-warning" />
+                                </Tooltip>
+                            </span>
+                            <span class="d-flex gap-2">
+                                <template v-for="type in extractTypeInfo(property).types" :key="type">
+                                    <a v-if="type.startsWith('#')" class="d-flex fw-bold type-box rounded fs-7 px-2 py-1" :href="type" @click.stop>
+                                        <span class="ref-type">{{ className(type) }}</span><eye-outline />
+                                    </a>
+                                    <span v-else class="type-box rounded fs-7 px-2 py-1">
+                                        {{ type }}
+                                    </span>
+                                </template>
+                                <component :is="collapsed ? ChevronDown : ChevronUp" class="arrow" />
+                            </span>
+                        </span>
+                    </template>
+                    <template #content>
+                        <PropertyDetail :show-dynamic="showDynamic" :is-dynamic="showDynamic && isDynamic(property)" :property="property">
+                            <template #markdown="{content}">
+                                <slot :content="content" name="markdown" />
+                            </template>
+                        </PropertyDetail>
+                    </template>
+                </Collapsible>
+            </div>
+        </template>
+    </Collapsible>
+</template>
+
+<script setup lang="ts">
+    import {extractTypeInfo, className} from "../../utils/schemaUtils";
+    import ChevronDown from "vue-material-design-icons/ChevronDown.vue";
+    import Collapsible from "../misc/Collapsible.vue";
+    import Tooltip from "../misc/Tooltip.vue";
+    import PropertyDetail from "./PropertyDetail.vue";
+    import ChevronUp from "vue-material-design-icons/ChevronUp.vue";
+    import Alert from "vue-material-design-icons/Alert.vue";
+    import Cancel from "vue-material-design-icons/Cancel.vue";
+    import AlphaBBox from "vue-material-design-icons/AlphaBBox.vue";
+    import type {JSONProperty} from "./PropertyType.vue";
+    import type {JSONSchema} from "./SchemaToHtml.vue";
+    import EyeOutline from "vue-material-design-icons/EyeOutline.vue";
+    import {ref, watch} from "vue";
+
+    withDefaults(defineProps<{ href?: string, sectionName: string, properties: [JSONProperty], showDynamic: boolean }>(), {
+        href: Math.random().toString(36).substring(2, 5),
+        showDynamic: true
+    });
+
+    const emit = defineEmits(["expand"]);
+
+    const initiallyExpanded = ref(false);
+
+    watch(
+        initiallyExpanded,
+        newInitiallyExpanded => {
+            if (newInitiallyExpanded) {
+                emit("expand");
+            }
+        }
+    );
+
+    const isDynamic = (property: JSONProperty): boolean => {
+        if (property["$dynamic"] === true) {
+            return true;
+        }
+
+        if (property["$dynamic"] === false) {
+            return false;
+        }
+
+        return property.oneOf?.some(prop => prop["$dynamic"] === true) ?? false;
+    };
+
+    function sortSchemaByRequired<T extends NonNullable<NonNullable<JSONSchema["properties"]>["properties"]>>(schema: T): T {
+        const requiredKeys = [];
+        const nonRequiredKeys = [];
+
+        for (const key in schema) {
+            if (typeof schema[key] === "object") {
+                if (schema[key].$required) {
+                    requiredKeys.push(key);
+                } else {
+                    nonRequiredKeys.push(key);
+                }
+            }
+        }
+
+        const sortedKeys = [...requiredKeys.sort(), ...nonRequiredKeys.sort()];
+
+        const sortedSchema: T = {} as T;
+        sortedKeys.forEach(key => {
+            sortedSchema[key] = schema[key];
+        });
+
+        return sortedSchema;
+    }
+</script>
+
+<style lang="scss" scoped>
+    @use "../../scss/variables" as variables;
+
+    .type-box, :deep(.type-box) {
+        border: 1px solid variables.$blue !important;
+        background: none;
+
+        .ref-type {
+            padding-right: 0.625rem;
+
+            + * {
+                margin-left: 0.625rem;
+            }
+        }
+    }
+
+    .property:not(:first-child) {
+        border-top: var(--bs-border-width) var(--bs-border-style) var(--bs-border-color);
+    }
+</style>