@forsakringskassan/docs-generator 2.5.0 → 2.7.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-D4vqQB-D.js');
 var path = require('node:path/posix');
 require('@vue/compiler-sfc');
-require('./vendor-BFdBzDIw.js');
+require('./vendor-B3CU63aM.js');
 require('typescript');
 require('node:url');
 require('fs');
@@ -22,16 +22,11 @@ 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('fs/promises');
 require('os');
 require('http');
 require('https');

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

@@ -1,6 +1,6 @@
 'use strict';
 
-var vendor = require('./vendor-BFdBzDIw.js');
+var vendor = require('./vendor-B3CU63aM.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-B3CU63aM.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-MuI6-bYd.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-D4vqQB-D.js');
 var vueDocgenApi = require('vue-docgen-api');
 var sass = require('sass');
 var node_url = require('node:url');
@@ -31,14 +31,9 @@ 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('fs/promises');
 require('os');
 require('http');
 require('https');
@@ -451,13 +446,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 +767,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),
@@ -1043,47 +1042,33 @@ async function navigationFileReader(filePath, basePath) {
   return [doc];
 }
 
-function resolveScssImport(filePath, throwError = true) {
-  const { dir, base } = path$1.parse(filePath);
-  const search = [`${base}.css`, `${base}.scss`, `_${base}.scss`, `${base}`];
-  for (const variant of search) {
-    try {
-      const moduleName = path$1.join(dir, variant);
-      const resolved = require.resolve(moduleName);
-      return node_url.pathToFileURL(resolved);
-    } catch (err) {
-      if (err.code !== "MODULE_NOT_FOUND") {
-        throw err;
-      }
-    }
-  }
-  if (throwError) {
-    throw new Error(`Failed to resolve "${filePath}"`);
-  }
-  return null;
-}
 const WEBPACK_NODE_MODULE_PREFIX = "~";
 const moduleImporter = {
-  canonicalize(url) {
-    const indexOfPrefix = url.indexOf(WEBPACK_NODE_MODULE_PREFIX);
-    if (indexOfPrefix >= 0) {
-      return resolveScssImport(url.slice(indexOfPrefix + 1));
-    }
-    if (url.startsWith("file://")) {
-      const path$1 = node_url.fileURLToPath(url);
-      const relative = path.isAbsolute(path$1) ? path.relative(__dirname, path$1) : path$1;
-      return resolveScssImport(relative.replace(/\\/g, "/"));
-    }
-    return resolveScssImport(url, false);
-  },
-  async load(url) {
-    const filepath = node_url.fileURLToPath(url);
-    const parsed = path.parse(filepath);
-    const contents = await fs.readFile(filepath, "utf-8");
-    return {
-      contents,
-      syntax: parsed.ext.slice(1) === "scss" ? "scss" : "css"
-    };
+  findFileUrl(url) {
+    let findUrl = url;
+    if (url.startsWith(WEBPACK_NODE_MODULE_PREFIX)) {
+      findUrl = url.substring(1);
+    }
+    const directory = path.dirname(findUrl);
+    const fileName = path.basename(findUrl);
+    const search = [
+      `${fileName}.css`,
+      `${fileName}.scss`,
+      `_${fileName}.scss`,
+      `${fileName}`
+    ];
+    for (const variant of search) {
+      try {
+        const moduleName = path.posix.join(directory, variant);
+        const resolved = require.resolve(moduleName);
+        return new URL(node_url.pathToFileURL(resolved));
+      } catch (err) {
+        if (err.code !== "MODULE_NOT_FOUND") {
+          throw err;
+        }
+      }
+    }
+    return null;
   }
 };
 
@@ -1385,7 +1370,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 +1692,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 +1786,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);
@@ -2139,7 +2123,7 @@ async function serve(options) {
   printMenu(server.address());
   const livereload = vendor.tinylr();
   livereload.listen(35729);
-  const watcher = vendor.chokidar.watch(options.watch);
+  const watcher = vendor.watch(options.watch);
   const rebuild = createRebuilder(options.rebuild, (filePath) => {
     const files = filePath.map((it) => {
       return path$1.relative(options.outputFolder, it);
@@ -2423,7 +2407,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-MuI6-bYd.js');
+require('./vendor-B3CU63aM.js');
 require('@vue/compiler-sfc');
 require('typescript');
 require('node:url');
@@ -19,16 +19,11 @@ 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('fs/promises');
 require('os');
 require('http');
 require('https');