743 new schema editor panel documentation view of the current schema (#747) (#749)

* Schema to markdown function added.

* Added documentation panel.

* Added documentation panel with download as markdown function.

* Removed some unused code.

* Added light mode support to documentation panel and changed DocumentationPanel.vue markdown to html functions with showdown library.

* - Linked properties to their definitions
- Added example blocks and default values
- Used describeSchema for detailed descriptions
- Documented oneOf, anyOf, allOf, if/then/else, not, etc.

* improve different things

* fix minor things

* refactor

* minor improvements

* hide only large enum values in spoiler

* fix sub schemas are properly linked

* make documentation code examples adapt to the current format

* add uni-directional synchronization between selected element from other panels to documentation panel

* minor bugfix

* fix oneOf reference and other things

* draw missing graph edges

* show message instead of error in docs view for empty schema

* show default and examples only if in document

* use same header style as in other panels and include documentation settings in it

* add documentation panel to settings

* show constraints only when needed

* reformat the code

* remove unused line

* establish connection of selected element also in other direction: markdown clicks are synchronized with other panels

* add schema title

* refactor anchor code

* make titles self refer to make it clickable

* remove duplicate entries

* add tests

* do not reformat markdown files in markdown test folder

* never repeat multiple occurrences in main document

* fix infinite loop for circular array schemas

* fix possible typeerror

* add tests

* used preprocessed schema for schema2docs and adjust tests to it

* add more test cases for schema 2 docs

* make unit test and formatting workflow also trigger for PRs from forks

* update to proper showndown import

* try fix dependency issue with showndown

* try fix dependency issue with showndown

* add showndown types

* replace union with old style as union is very new and not all browsers support it

* replace isDisjoint with old style as union is very new and not all browsers support it

* prettify

---------

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

Author: Logende

.github/workflows/npm-test.yml

@@ -1,6 +1,6 @@
 name: Node.js CI
 
-on: [push, workflow_dispatch]
+on: [push, workflow_dispatch, pull_request]
 
 jobs:
   build:

meta_configurator/.eslintignore

@@ -2,3 +2,4 @@
 node_modules
 .vscode
 dist
+src/utility/documentation/__tests__/**/*.md

meta_configurator/package-lock.json

@@ -55,6 +55,7 @@
     "primeicons": "^7.0.0",
     "primevue": "^4.2.5",
     "quicktype-core": "^23.0.171",
+    "showdown": "^2.1.0",
     "vue": "^3.5.13",
     "vue-flow": "^0.3.0",
     "vue-router": "^4.3.2",
@@ -68,6 +69,7 @@
     "@types/jsdom": "^21.1.1",
     "@types/json-pointer": "^1.0.31",
     "@types/node": "^18.16.8",
+    "@types/showdown": "^2.0.6",
     "@types/yaml": "^1.9.7",
     "@typescript-eslint/eslint-plugin": "^5.59.0",
     "@vitejs/plugin-vue": "^4.2.3",

meta_configurator/package.json

@@ -8,6 +8,7 @@ import DebugPanel from '@/components/panels/debug-panel/DebugPanel.vue';
 import AiPromptsPanel from '@/components/panels/ai-prompts/AiPromptsPanel.vue';
 import ListAnalysisPanel from './list-analysis/ListAnalysisPanel.vue';
 import TestPanel from '@/components/panels/test-panel/TestPanel.vue';
+import DocumentationPanel from '@/components/panels/documentation/DocumentationPanel.vue';
 
 export const panelTypeTextEditor: PanelTypeDefinition = {
   getComponent: () => CodeEditorPanel,
@@ -65,6 +66,14 @@ export const panelTypeTest: PanelTypeDefinition = {
   name: 'test',
 };
 
+export const panelTypeDocementation: PanelTypeDefinition = {
+  getComponent: () => DocumentationPanel,
+  supportedModes: [SessionMode.SchemaEditor],
+  label: 'Markdown documentation of the schema',
+  icon: 'fa-solid fa-book',
+  name: 'documentation',
+};
+
 /**
  * Registers the default panel types, which are GuiEditor, TextEditor, Schema Diagram, Ai Prompts and Debug.
  */
@@ -76,4 +85,5 @@ export function registerDefaultPanelTypes() {
   panelTypeRegistry.registerPanelType('tableView', panelTypeListAnalysis);
   panelTypeRegistry.registerPanelType('debug', panelTypeDebug);
   panelTypeRegistry.registerPanelType('test', panelTypeTest);
+  panelTypeRegistry.registerPanelType('documentation', panelTypeDocementation);
 }

meta_configurator/src/components/panels/defaultPanelTypes.ts

@@ -0,0 +1,252 @@
+<script setup lang="ts">
+import {SessionMode} from '@/store/sessionMode';
+import {computed, onMounted, onUnmounted, ref, watch} from 'vue';
+import {getSchemaForMode, getSessionForMode} from '@/data/useDataLink';
+import {schemaToMarkdown} from '@/utility/documentation/schemaToMarkdown';
+import {downloadMarkdown} from '@/components/panels/documentation/downloadMarkdown';
+import showdown from 'showdown';
+import type {Path} from '@/utility/path';
+import DocumentationSettingsPanel from '@/components/panels/documentation/DocumentationSettingsPanel.vue';
+import {asciiToPath, pathToAscii} from '@/utility/pathUtils';
+import {getSchemaTitle} from '@/schema/schemaReadingUtils';
+
+const props = defineProps<{
+  sessionMode: SessionMode;
+}>();
+
+const schema = getSchemaForMode(SessionMode.DataEditor);
+const schemaSession = getSessionForMode(SessionMode.SchemaEditor);
+const markdown = computed(() =>
+  schemaToMarkdown(schema.schemaPreprocessed.value, getSchemaTitle(schema.schemaWrapper.value))
+);
+
+const converter = new showdown.Converter({
+  tables: true,
+  ghCompatibleHeaderId: true,
+  requireSpaceBeforeHeadingText: true,
+});
+const renderedHtml = computed(() => converter.makeHtml(markdown.value));
+
+// DOM ref for rendered markdown
+const docsRef = ref<HTMLElement | null>(null);
+
+// scroll when selection changes
+watch(
+  () => schemaSession.currentSelectedElement.value,
+  path => scrollToPath(path),
+  {deep: true}
+);
+
+function scrollToPath(path: Path | null) {
+  if (!path) return;
+  const anchorId = pathToAscii(path);
+  const el = document.getElementById(anchorId);
+  el?.scrollIntoView({behavior: 'smooth', block: 'start'});
+}
+
+function handleDownloadClick() {
+  downloadMarkdown(markdown.value);
+}
+
+// anchor click handler
+function onAnchorClick(evt: MouseEvent) {
+  const target = evt.target as HTMLElement;
+  if (target.tagName !== 'A') return;
+  const href = (target as HTMLAnchorElement).getAttribute('href');
+  if (!href?.startsWith('#')) return;
+
+  evt.preventDefault(); // stop browser default jump
+  const id = href.slice(1); // remove '#'
+  try {
+    const path = asciiToPath(id); // reverse mapping
+    schemaSession.currentSelectedElement.value = path; // sync to other view
+    scrollToPath(path); // smooth scroll (optional)
+  } catch (e) {
+    console.warn('Invalid anchor id:', id, e);
+  }
+}
+
+onMounted(() => docsRef.value?.addEventListener('click', onAnchorClick));
+onUnmounted(() => docsRef.value?.removeEventListener('click', onAnchorClick));
+</script>
+
+<template>
+  <div class="documentation-panel">
+    <DocumentationSettingsPanel />
+    <div ref="docsRef" class="rendered-docs" v-html="renderedHtml"></div>
+    <div style="text-align: center; margin-top: 1rem">
+      <button class="download-btn" @click="handleDownloadClick">Download as Markdown</button>
+    </div>
+  </div>
+</template>
+
+<style>
+.documentation-panel {
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.heading {
+  font-size: 24px;
+  font-weight: bold;
+  text-align: center;
+  margin: 1rem auto 0.5rem;
+  color: var(--p-primary-active-color);
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+
+.rendered-docs {
+  flex: 1;
+  overflow-y: auto;
+  padding: 1rem 1.5rem;
+  font-size: 16px;
+  line-height: 1.6;
+  color: var(--p-primary-active-color);
+  background-color: var(--p-primary-background);
+  white-space: normal;
+  font-family: 'Segoe UI', sans-serif;
+  scroll-behavior: smooth;
+  position: relative;
+}
+
+.rendered-docs h1[id],
+.rendered-docs h2[id],
+.rendered-docs h3[id],
+.rendered-docs h4[id] {
+  scroll-margin-top: 80px;
+}
+
+.rendered-docs h1,
+.rendered-docs h2,
+.rendered-docs h3,
+.rendered-docs h4,
+.rendered-docs p,
+.rendered-docs td,
+.rendered-docs th {
+  color: var(--p-primary-active-color);
+}
+
+.rendered-docs h1,
+.rendered-docs h2,
+.rendered-docs h3,
+.rendered-docs h4 {
+  font-weight: bold;
+  display: block;
+  margin-top: 1.25em;
+}
+
+.rendered-docs h1 {
+  font-size: 32px;
+  margin: 2rem 0 1rem;
+}
+
+.rendered-docs h2 {
+  font-size: 26px;
+  margin: 1.75rem 0 0.75rem;
+}
+
+.rendered-docs h3 {
+  font-size: 22px;
+  margin: 1.5rem 0 0.5rem;
+}
+
+.rendered-docs h4 {
+  font-size: 18px;
+  margin: 1.25rem 0 0.5rem;
+}
+/* Style for all unordered lists in rendered docs */
+.rendered-docs ul {
+  list-style-type: disc;
+  margin: 0.8em 0 0.8em 1.5em; /* vertical spacing and indentation */
+  padding-left: 0;
+}
+
+/* Nested unordered lists get increased indentation and different bullet style */
+.rendered-docs ul ul {
+  list-style-type: circle;
+  margin-left: 1.5em;
+  margin-top: 0.4em;
+  margin-bottom: 0.4em;
+}
+
+.rendered-docs ul ul ul {
+  list-style-type: square;
+  margin-left: 1.5em;
+  margin-top: 0.3em;
+  margin-bottom: 0.3em;
+}
+
+/* List items spacing */
+.rendered-docs li {
+  margin: 0.2em 0;
+  line-height: 1.4;
+}
+
+/* Links inside list items */
+.rendered-docs li a {
+  color: var(--p-primary-active-color);
+  text-decoration: none;
+}
+
+.rendered-docs li a:hover {
+  text-decoration: underline;
+}
+
+.rendered-docs hr {
+  border: none;
+  border-top: 1px solid var(--p-border-color, #555);
+  margin: 2rem 0;
+}
+
+.rendered-docs table {
+  border-collapse: collapse;
+  width: 100%;
+  margin-top: 1em;
+  margin-bottom: 2em;
+  background-color: var(--p-primary-background);
+  font-size: 15px;
+}
+
+.rendered-docs th,
+.rendered-docs td {
+  border: 1px solid var(--p-primary-background, #444);
+  padding: 8px 12px;
+  text-align: left;
+}
+
+.rendered-docs th {
+  background-color: var(--p-primary-background);
+  font-weight: bold;
+}
+
+.rendered-docs td {
+  background-color: var(--p-primary-background);
+}
+
+.rendered-docs pre {
+  background-color: var(--p-highlight-background, var(--p-primary-hover-color));
+  color: var(--p-primary-active-color);
+  padding: 12px;
+  border-radius: 4px;
+  overflow-x: auto;
+  margin-top: 1em;
+}
+
+.download-btn {
+  background-color: var(--p-primary-background);
+  color: var(--p-primary-active-color);
+  border: 1px solid var(--p-border-color, #666);
+  padding: 0.5rem 1rem;
+  border-radius: 6px;
+  font-size: 15px;
+  cursor: pointer;
+  transition: background 0.2s;
+}
+
+.download-btn:hover {
+  background-color: var(--p-highlight-color);
+}
+</style>