@forsakringskassan/docs-generator 2.5.0 → 2.6.0

package/README.md

@@ -206,6 +206,10 @@ The following statuses are recognized:
 
 Document title used for `<title>` and `<nav>`
 
+#### `short-title`
+
+Document title used when a shorter title is needed, e.g. site navigation.
+
 #### `visible`
 
 Set to `false` to hide document from navigation menu.
@@ -218,20 +222,34 @@ Default `true`.
 
 ### Inline tags
 
-#### `{@link ...}`
+#### `{@@link ...}`
 
 Implicit title:
 
 ```md
-Use the {@link MyAwesomeComponent} component.
+Use the {@@link MyAwesomeComponent} component.
 ```
 
 Explicit title:
 
 ```md
-Use the {@link MyAwesomeComponent awesome component}.
+Use the {@@link MyAwesomeComponent awesome component}.
+```
+
+#### `{@@optional}`
+
+Creates a tag (badge) to mark something as optional.
+
+**Input:**
+
+```md
+{@@optional}
 ```
 
+**Output:**
+
+{@optional}
+
 ### Templating
 
 The [Nunjucks](https://mozilla.github.io/nunjucks/) templating engine is used for rendering documents to HTML.

package/dist/compile-example.js

@@ -3,10 +3,10 @@
 var path$1 = require('node:path');
 var esbuild = require('esbuild');
 var vue = require('vue');
-var vue3 = require('./vue3-Cv0MDe04.js');
+var vue3 = require('./vue3-CNEpTgeX.js');
 var path = require('node:path/posix');
 require('@vue/compiler-sfc');
-require('./vendor-BFdBzDIw.js');
+require('./vendor-CYT__b1C.js');
 require('typescript');
 require('node:url');
 require('fs');
@@ -22,16 +22,10 @@ require('assert');
 require('path');
 require('readline');
 require('events');
-require('child_process');
-require('node:stream/promises');
-require('node:child_process');
-require('node:util');
 require('node:process');
-require('node:tty');
-require('node:timers/promises');
-require('node:os');
-require('node:v8');
-require('node:buffer');
+require('node:util');
+require('node:child_process');
+require('node:stream/promises');
 require('os');
 require('http');
 require('https');

package/dist/{create-markdown-renderer-iznOQQKw.js → create-markdown-renderer-Bun8U6bd.js}

@@ -1,6 +1,6 @@
 'use strict';
 
-var vendor = require('./vendor-BFdBzDIw.js');
+var vendor = require('./vendor-CYT__b1C.js');
 var path = require('node:path/posix');
 var path$1 = require('node:path');
 require('crypto');
@@ -81,7 +81,15 @@ class SoftError extends Error {
 }
 
 function processInlineTags(tags, doc, docs, text, handleSoftError) {
-  return text.replace(/{@([\S}]+)([^}]*)}/g, (_, name, content) => {
+  return text.replace(/{@(@?)([^{}]+)}/g, (_, escape, content) => {
+    if (escape) {
+      return `{@${content}}`;
+    }
+    const match = content.match(/^(\S+)($|\s[^]+)$/);
+    if (!match) {
+      return `{@${content}}`;
+    }
+    const [, name, text2] = match;
     const tag = tags.find((it) => it.name === name);
     if (!tag) {
       return handleSoftError(
@@ -92,7 +100,7 @@ function processInlineTags(tags, doc, docs, text, handleSoftError) {
       );
     }
     try {
-      return tag.handler(doc, docs, content.trim());
+      return tag.handler(doc, docs, text2.trim());
     } catch (err) {
       if (err instanceof SoftError) {
         return handleSoftError(err);
@@ -164,7 +172,15 @@ const linkTag = {
   }
 };
 
-const inlineTags = [linkTag];
+const optionalTag = {
+  name: "optional",
+  description: "Create a tag for symbolize optional content",
+  handler() {
+    return `<span class="docs-tag docs-tag--default">Optional</span>`;
+  }
+};
+
+const inlineTags = [linkTag, optionalTag];
 
 function findTestId(tags) {
   const prefix = "test-id=";
@@ -461,9 +477,100 @@ function imageResources(options) {
   };
 }
 
+function altContainer(context) {
+  const { md, env, docs } = context;
+  return (tokens, index) => {
+    const token = tokens[index];
+    const needle = token.info;
+    const doc = findDocument(docs, needle);
+    if (doc && doc.format === "markdown") {
+      return md.render(doc.body, env);
+    }
+    return md.render(token.content, env);
+  };
+}
+
+function apiContainer(context) {
+  const { md, env, docs, included, handleSoftError } = context;
+  return (tokens, index) => {
+    const token = tokens[index];
+    const needle = token.content.trim();
+    const doc = findDocument(docs, needle);
+    if (!doc) {
+      return handleSoftError(
+        new SoftError(
+          "EINCLUDETARGET",
+          `No document matches "${needle}" when trying to include content`,
+          { id: needle }
+        )
+      );
+    }
+    if (included.has(doc.id)) {
+      return handleSoftError(
+        new SoftError(
+          "EINCLUDERECURSION",
+          `Recursion detected when including document "${doc.id}"`
+        )
+      );
+    }
+    included.add(doc.id);
+    if (doc.format === "html") {
+      return doc.body;
+    }
+    const content = md.render(doc.body, env);
+    return (
+      /* HTML */
+      ` <div>${content}</div> `
+    );
+  };
+}
+
+const defaultTitle = {
+  info: "INFO",
+  warning: "WARNING",
+  danger: "DANGER"
+};
+function messageboxContainer(context, options, alias) {
+  const { md, env } = context;
+  function getTitle(variant, customTitle) {
+    if (customTitle && customTitle.length > 0) {
+      return customTitle.join(" ");
+    } else {
+      return options.title[variant] ?? defaultTitle[variant] ?? "";
+    }
+  }
+  function parseInfo(info) {
+    if (alias) {
+      const variant = alias;
+      const customTitle = info ? info.split(" ") : [];
+      const title = getTitle(variant, customTitle);
+      return { variant, title };
+    } else {
+      const [variant = "info", ...customTitle] = info ? info.split(" ") : [];
+      const title = getTitle(variant, customTitle);
+      return { variant, title };
+    }
+  }
+  return (tokens, index) => {
+    const token = tokens[index];
+    const { variant, title } = parseInfo(token.info);
+    const text = token.content.trim();
+    const content = md.render(text, env);
+    return (
+      /* HTML */
+      `
+            <div class="docs-messagebox docs-messagebox--${variant}">
+                ${title ? `<p class="docs-messagebox__title">${title}</p>` : ""}
+                ${content}
+            </div>
+        `
+    );
+  };
+}
+
 const markerStr = ":";
 const markerChar = markerStr.charCodeAt(0);
-function parser(md, options) {
+function containerParser(md, options) {
   function container(state, startLine, endLine, silent) {
     let pos = state.bMarks[startLine] + state.tShift[startLine];
     let max = state.eMarks[startLine];
@@ -484,8 +591,9 @@ function parser(md, options) {
       return false;
     }
     const markup = state.src.slice(mem, pos);
-    const params = state.src.slice(pos, max).trim();
-    const kind = params.split(" ", 2)[0];
+    const params = state.src.slice(pos, max).trim().split(/\s+/);
+    const kind = params[0];
+    const info = params.slice(1).join(" ");
     if (silent) {
       return true;
     }
@@ -521,7 +629,7 @@ function parser(md, options) {
     len = state.sCount[startLine];
     state.line = nextLine + (haveEndMarker ? 1 : 0);
     const token = state.push(`doc_${kind}`, "div", 0);
-    token.info = params;
+    token.info = info?.trim();
     token.content = state.getLines(startLine + 1, nextLine, len, true);
     token.markup = markup;
     token.map = [startLine, state.line];
@@ -534,49 +642,28 @@ function parser(md, options) {
     md.renderer.rules[`doc_${kind}`] = fn;
   }
 }
-function include(docs, env, included, handleSoftError) {
+function containerRenderer(docs, env, included, handleSoftError, options) {
   return function(md) {
-    md.use(parser, {
-      api(tokens, index) {
-        const token = tokens[index];
-        const needle = token.content.trim();
-        const doc = findDocument(docs, needle);
-        if (!doc) {
-          return handleSoftError(
-            new SoftError(
-              "EINCLUDETARGET",
-              `No document matches "${needle}" when trying to include content`,
-              { id: needle }
-            )
-          );
-        }
-        if (included.has(doc.id)) {
-          return handleSoftError(
-            new SoftError(
-              "EINCLUDERECURSION",
-              `Recursion detected when including document "${doc.id}"`
-            )
-          );
-        }
-        included.add(doc.id);
-        if (doc.format === "html") {
-          return doc.body;
-        }
-        const content = md.render(doc.body, env);
-        return (
-          /* HTML */
-          ` <div>${content}</div> `
-        );
-      },
-      alt(tokens, index) {
-        const token = tokens[index];
-        const needle = token.info.split(" ")[1];
-        const doc = findDocument(docs, needle);
-        if (doc && doc.format === "markdown") {
-          return md.render(doc.body, env);
-        }
-        return md.render(token.content, env);
-      }
+    const context = {
+      md,
+      env,
+      docs,
+      included,
+      handleSoftError
+    };
+    md.use(containerParser, {
+      alt: altContainer(context),
+      api: apiContainer(context),
+      messagebox: messageboxContainer(context, options.messagebox),
+      /* aliases for messagebox containers */
+      info: messageboxContainer(context, options.messagebox, "info"),
+      tip: messageboxContainer(context, options.messagebox, "tip"),
+      warning: messageboxContainer(
+        context,
+        options.messagebox,
+        "warning"
+      ),
+      danger: messageboxContainer(context, options.messagebox, "danger")
     });
   };
 }
@@ -617,6 +704,7 @@ function createMarkdownRenderer(options) {
   const md = vendor.MarkdownIt({
     html: true
   });
+  md.use(vendor.deflist_plugin);
   md.use(
     codePreview({
       generateExample: options.generateExample
@@ -628,7 +716,11 @@ function createMarkdownRenderer(options) {
       addResource: options.addResource
     })
   );
-  md.use(include(docs, env, included, options.handleSoftError));
+  md.use(
+    containerRenderer(docs, env, included, options.handleSoftError, {
+      messagebox: { title: {}, ...options.messagebox }
+    })
+  );
   md.use(table());
   md.use(codeInline());
   return {

package/dist/index.d.ts

@@ -213,6 +213,35 @@ export declare interface GeneratorOptions {
      * `function setup(options: { rootComponent: string, selector: string }): void`
      */
     setupPath: string;
+    /**
+     * Options for markdown renderer.
+     */
+    markdown: {
+        /**
+         * Options for markdown messagebox container.
+         */
+        messagebox: {
+            /**
+             * Default titles for messageboxes.
+             *
+             * If a title is the empty string `""` the usage of title is
+             * disabled by default.
+             *
+             * @example
+             * ```json
+             * {
+             *   "title": {
+             *     "info": "Information",
+             *     "tip": "Tips",
+             *     "warning": "Varning",
+             *     "danger": "Se upp!"
+             *   }
+             * }
+             * ```
+             */
+            title?: Record<string, string>;
+        };
+    };
 }
 
 /**
@@ -349,6 +378,7 @@ export declare interface NavigationSection {
  */
 export declare interface NormalizedDocumentAttributes {
     title?: string;
+    shortTitle?: string;
     layout?: string;
     status?: string;
     badge?: DocumentBadge;

package/dist/index.js

@@ -1,17 +1,17 @@
 'use strict';
 
 var fs = require('node:fs/promises');
-var vendor = require('./vendor-BFdBzDIw.js');
+var vendor = require('./vendor-CYT__b1C.js');
 var path = require('node:path');
 var require$$1 = require('crypto');
-var createMarkdownRenderer = require('./create-markdown-renderer-iznOQQKw.js');
+var createMarkdownRenderer = require('./create-markdown-renderer-Bun8U6bd.js');
 var node_child_process = require('node:child_process');
 var path$1 = require('node:path/posix');
 require('node:crypto');
 var util = require('node:util');
 var fs$1 = require('node:fs');
 var vue = require('vue');
-var vue3 = require('./vue3-Cv0MDe04.js');
+var vue3 = require('./vue3-CNEpTgeX.js');
 var vueDocgenApi = require('vue-docgen-api');
 var sass = require('sass');
 var node_url = require('node:url');
@@ -31,14 +31,8 @@ require('assert');
 require('path');
 require('readline');
 require('events');
-require('child_process');
-require('node:stream/promises');
 require('node:process');
-require('node:tty');
-require('node:timers/promises');
-require('node:os');
-require('node:v8');
-require('node:buffer');
+require('node:stream/promises');
 require('os');
 require('http');
 require('https');
@@ -451,13 +445,16 @@ function topnavProcessor(filename, title) {
 }
 
 async function getGitBranch() {
-  const { CHANGE_BRANCH, CHANGE_NAME } = process.env;
+  const { CHANGE_BRANCH, CHANGE_NAME, GITHUB_HEAD_REF } = process.env;
   if (CHANGE_BRANCH) {
     return CHANGE_BRANCH;
   }
   if (CHANGE_NAME) {
     return CHANGE_NAME;
   }
+  if (GITHUB_HEAD_REF) {
+    return GITHUB_HEAD_REF;
+  }
   const branch = await runCommand(
     "git rev-parse --abbrev-ref HEAD",
     "unknown"
@@ -769,6 +766,7 @@ function parseFile$1(filePath, basePath, content) {
     visible: attributes.visible ?? true,
     attributes: {
       title: attributes.title ?? name,
+      shortTitle: attributes["short-title"],
       layout: attributes.layout,
       status: attributes.status,
       badge: getBadge(attributes),
@@ -1385,7 +1383,7 @@ function generateNavtree(docs) {
   }
   for (const doc of docs) {
     const [name, isSection] = pathFromDoc(doc);
-    const title = doc.attributes.title ?? doc.fileInfo.name;
+    const title = doc.attributes.shortTitle ?? doc.attributes.title ?? doc.fileInfo.name;
     const sortorder = doc.attributes.sortorder;
     if (doc.attributes.href) {
       const parent2 = attach(name);
@@ -1707,13 +1705,11 @@ async function compileExamples(options) {
     external: vendors.map((it) => it.package),
     tasks: dirtyTasks
   };
-  const result = await vendor.execa("node", [scriptPath], {
-    input: JSON.stringify(batch),
-    all: true
+  const result = await vendor.spawn("node", [scriptPath], {
+    stdin: { string: JSON.stringify(batch) }
   });
-  const hasOutput = result.all ? result.all.length > 0 : false;
-  if (hasOutput) {
-    console.log(result.all);
+  if (result.output.length > 0) {
+    console.log(result.output);
   }
 }
 async function compileStandalones(options) {
@@ -1803,7 +1799,8 @@ async function render(doc, docs, nav, vendors, options) {
     },
     handleSoftError(error) {
       throw error;
-    }
+    },
+    messagebox: options.markdown.messagebox
   });
   njk.addFilter("marked", (content2) => {
     return markdownRenderer.render(doc, content2);
@@ -2423,7 +2420,8 @@ class Generator {
         cacheFolder,
         exampleFolders,
         templateFolders,
-        setupPath
+        setupPath,
+        markdown: {}
       }),
       ...this.processors
     ];

package/dist/markdown.d.ts

@@ -183,6 +183,13 @@ export declare interface MarkdownOptions {
      * @returns A replacement string or rethrows error.
      */
     handleSoftError(error: SoftErrorType): string;
+    /**
+     * Options for messagebox container.
+     */
+    messagebox?: {
+        /** Default titles for messageboxes */
+        title?: Record<string, string>;
+    };
 }
 
 /**
@@ -206,6 +213,7 @@ export declare interface MarkdownRenderer {
  */
 export declare interface NormalizedDocumentAttributes {
     title?: string;
+    shortTitle?: string;
     layout?: string;
     status?: string;
     badge?: DocumentBadge;

package/dist/markdown.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var createMarkdownRenderer = require('./create-markdown-renderer-iznOQQKw.js');
-require('./vendor-BFdBzDIw.js');
+var createMarkdownRenderer = require('./create-markdown-renderer-Bun8U6bd.js');
+require('./vendor-CYT__b1C.js');
 require('@vue/compiler-sfc');
 require('typescript');
 require('node:url');
@@ -19,16 +19,10 @@ require('assert');
 require('path');
 require('readline');
 require('events');
-require('child_process');
-require('node:stream/promises');
-require('node:child_process');
-require('node:util');
 require('node:process');
-require('node:tty');
-require('node:timers/promises');
-require('node:os');
-require('node:v8');
-require('node:buffer');
+require('node:util');
+require('node:child_process');
+require('node:stream/promises');
 require('os');
 require('http');
 require('https');

package/dist/runtime.js

@@ -139392,6 +139392,137 @@ onContentReady(() => {
   }
 });
 
+// src/runtime/debounce.ts
+function debounce2(func, delay2, immediate = false) {
+  let timeout2 = null;
+  return function functionToExecute(...args) {
+    const timedOutFunction = () => {
+      timeout2 = null;
+      if (!immediate) {
+        func.apply(this, args);
+      }
+    };
+    const callNow = immediate && !timeout2;
+    if (timeout2 !== null) {
+      clearTimeout(timeout2);
+    }
+    timeout2 = setTimeout(timedOutFunction, delay2);
+    if (callNow) {
+      func.apply(this);
+    }
+  };
+}
+
+// src/runtime/topnav.ts
+function getElementsRefs() {
+  const nav = document.querySelector("#topnav");
+  if (!nav) {
+    return;
+  }
+  const menuItems = Array.from(
+    nav.querySelectorAll(".imenu__list__item")
+  );
+  const moreItem = menuItems.pop();
+  const moreButton = moreItem.querySelector("button");
+  const popoverContainer = moreItem.querySelector(".ipopupmenu");
+  const popover = popoverContainer.querySelector(".ipopupmenu__list");
+  const popoverItems = Array.from(
+    popover.querySelectorAll(".ipopupmenu__list__item")
+  );
+  const highlightIndex = menuItems.findIndex(
+    (it) => it.classList.contains("imenu__list__item--highlight")
+  );
+  const itemPairs = menuItems.map((menu, index2) => ({
+    menu,
+    popover: popoverItems[index2]
+  }));
+  return {
+    nav,
+    moreItem,
+    moreButton,
+    popoverContainer,
+    popover,
+    itemPairs,
+    highlightIndex
+  };
+}
+function setPopoverVisibility(visible, refs) {
+  refs.popover.style.visibility = visible ? "visible" : "hidden";
+  refs.moreButton.ariaExpanded = visible.toString();
+}
+function togglePopover(event3, refs) {
+  event3.stopPropagation();
+  setPopoverVisibility(refs.popover.style.visibility === "hidden", refs);
+}
+function closePopoverOnEsc(event3, refs) {
+  if (event3.key === "Escape") {
+    setPopoverVisibility(false, refs);
+    refs.moreButton.focus();
+  }
+}
+function onClickItem(event3) {
+  const clickable = event3.target.querySelector(
+    "a, button"
+  );
+  clickable.click();
+}
+function onClickPopover(event3) {
+  event3.stopPropagation();
+}
+function hasOverflow(container2, content) {
+  return content.offsetLeft + content.offsetWidth > container2.offsetLeft + container2.offsetWidth;
+}
+function setMenuItemVisibility(itemPair, visible) {
+  itemPair.menu.style.visibility = visible ? "visible" : "hidden";
+  itemPair.popover.style.display = visible ? "none" : "block";
+}
+function calculateVisibility(refs) {
+  refs.moreItem.style.left = "0";
+  const menuItems = refs.itemPairs.map((item) => item.menu);
+  let overflowIndex = menuItems.findIndex((it) => hasOverflow(refs.nav, it));
+  if (overflowIndex === -1) {
+    refs.itemPairs.forEach((it) => setMenuItemVisibility(it, true));
+    refs.moreItem.style.visibility = "hidden";
+    setPopoverVisibility(false, refs);
+    return;
+  }
+  if (hasOverflow(refs.nav, {
+    offsetLeft: menuItems[overflowIndex].offsetLeft,
+    offsetWidth: refs.moreItem.offsetWidth
+  })) {
+    overflowIndex--;
+  }
+  refs.itemPairs.forEach(
+    (it, index2) => setMenuItemVisibility(it, index2 < overflowIndex)
+  );
+  const classOperation = refs.highlightIndex >= overflowIndex ? "add" : "remove";
+  refs.moreItem.classList[classOperation]("imenu__list__item--highlight");
+  refs.moreItem.style.left = `${menuItems[overflowIndex].offsetLeft}px`;
+  refs.moreItem.style.visibility = "visible";
+  const popupTop = refs.moreItem.offsetHeight + 16;
+  refs.popover.style.top = `${popupTop}px`;
+}
+onContentReady(() => {
+  const refs = getElementsRefs();
+  if (!refs) {
+    return;
+  }
+  window.addEventListener(
+    "resize",
+    debounce2(() => calculateVisibility(refs), 100)
+  );
+  document.addEventListener("click", () => setPopoverVisibility(false, refs));
+  refs.itemPairs.forEach((pair) => {
+    pair.menu.addEventListener("click", onClickItem);
+    pair.popover.addEventListener("click", onClickItem);
+  });
+  refs.moreItem.addEventListener("click", (e6) => togglePopover(e6, refs));
+  refs.moreItem.addEventListener("keyup", (e6) => closePopoverOnEsc(e6, refs));
+  refs.popoverContainer.addEventListener("click", onClickPopover);
+  setPopoverVisibility(false, refs);
+  calculateVisibility(refs);
+});
+
 // src/runtime/index.ts
 window.toggleMarkup = toggleMarkup;
 /*! Bundled license information: