tools,doc: add support for several flavors of JS code snippets

Enable code example using both modern ESM syntax and legacy CJS syntax.
It adds a toggle on the web interface to let users switch from one
JavaScript flavor to the other.

Author: aduh95

doc/api/wasi.md

@@ -10,7 +10,7 @@ The WASI API provides an implementation of the [WebAssembly System Interface][]
 specification. WASI gives sandboxed WebAssembly applications access to the
 underlying operating system via a collection of POSIX-like functions.
 
-```js
+```js esm
 import fs from 'fs';
 import { WASI } from 'wasi';
 
@@ -28,6 +28,26 @@ const instance = await WebAssembly.instantiate(wasm, importObject);
 
 wasi.start(instance);
 ```
+```js cjs
+'use strict';
+const fs = require('fs');
+const { WASI } = require('wasi');
+const wasi = new WASI({
+  args: process.argv,
+  env: process.env,
+  preopens: {
+    '/sandbox': '/some/real/path/that/wasm/can/access'
+  }
+});
+const importObject = { wasi_snapshot_preview1: wasi.wasiImport };
+
+(async () => {
+  const wasm = await WebAssembly.compile(fs.readFileSync('./demo.wasm'));
+  const instance = await WebAssembly.instantiate(wasm, importObject);
+
+  wasi.start(instance);
+})();
+```
 
 To run the above example, create a new WebAssembly text format file named
 `demo.wat`:

doc/api_assets/js-flavor-cjs.svg

@@ -765,6 +765,33 @@ kbd {
   display: block;
 }
 
+.js-flavor-selector {
+  appearance: none;
+  float: right;
+  background-image: url(./js-flavor-cjs.svg);
+  background-size: contain;
+  background-repeat: no-repeat;
+  width: 142px;
+  height: 20px;
+}
+.js-flavor-selector:checked {
+  background-image: url(./js-flavor-esm.svg);
+}
+.js-flavor-selector:not(:checked) ~ .esm,
+.js-flavor-selector:checked ~ .cjs {
+  display: none;
+}
+.dark-mode .js-flavor-selector {
+  filter: invert(1);
+}
+@supports (aspect-ratio: 1 / 1) {
+  .js-flavor-selector {
+    height: 1.5em;
+    width: auto;
+    aspect-ratio: 2719 / 384;
+  }
+}
+
 @media print {
   html {
     height: auto;
@@ -815,4 +842,24 @@ kbd {
   #apicontent {
     overflow: hidden;
   }
+  .js-flavor-selector {
+    display: none;
+  }
+  .js-flavor-selector + * {
+    margin-bottom: 2rem;
+    padding-bottom: 2rem;
+    border-bottom: 1px solid var(--color-text-primary);
+  }
+  .js-flavor-selector ~ * {
+    display: block !important;
+    background-position: top right;
+    background-size: 142px 20px;
+    background-repeat: no-repeat;
+  }
+  .js-flavor-selector ~ .cjs {
+    background-image: url(./js-flavor-cjs.svg);
+  }
+  .js-flavor-selector ~ .esm {
+    background-image: url(./js-flavor-esm.svg);
+  }
 }

doc/api_assets/js-flavor-esm.svg

@@ -129,7 +129,15 @@ const testData = [
   {
     file: fixtures.path('document_with_special_heading.md'),
     html: '<title>Sample markdown with special heading |',
-  }
+  },
+  {
+    file: fixtures.path('document_with_esm_and_cjs_code_snippet.md'),
+    html: '<input class="js-flavor-selector" type="checkbox" checked',
+  },
+  {
+    file: fixtures.path('document_with_cjs_and_esm_code_snippet.md'),
+    html: '<input class="js-flavor-selector" type="checkbox" aria-label',
+  },
 ];
 
 const spaces = /\s/g;

doc/api_assets/style.css

@@ -0,0 +1,11 @@
+# Usage and Example
+
+CJS snippet is first, it should be the one displayed by default.
+
+```js cjs
+require('path');
+```
+
+```js esm
+import 'node:url';
+```

test/doctool/test-doctool-html.js

@@ -0,0 +1,11 @@
+# Usage and Example
+
+ESM snippet is first, it should be the one displayed by default.
+
+```js esm
+import 'node:url';
+```
+
+```js cjs
+require('path');
+```

test/fixtures/document_with_cjs_and_esm_code_snippet.md

@@ -187,14 +187,16 @@ function linkJsTypeDocs(text) {
   return parts.join('`');
 }
 
+const isJSFlavorSnippet = (node) => node.lang === 'js' && node.meta;
+
 // Preprocess headers, stability blockquotes, and YAML blocks.
 function preprocessElements({ filename }) {
   return (tree) => {
     const STABILITY_RE = /(.*:)\s*(\d)([\s\S]*)/;
     let headingIndex = -1;
     let heading = null;
 
-    visit(tree, null, (node, index) => {
+    visit(tree, null, (node, index, parent) => {
       if (node.type === 'heading') {
         headingIndex = index;
         heading = node;
@@ -204,15 +206,48 @@ function preprocessElements({ filename }) {
             `No language set in ${filename}, ` +
             `line ${node.position.start.line}`);
         }
-        const language = (node.lang || '').split(' ')[0];
-        const highlighted = getLanguage(language) ?
-          highlight(language, node.value).value :
-          node.value;
+        const highlighted =
+          `<code class='language-${node.lang} ${node.meta}'>` +
+          (getLanguage(node.lang || '') ?
+            highlight(node.lang, node.value) : node).value +
+          '</code>';
         node.type = 'html';
-        node.value = '<pre>' +
-          `<code class = 'language-${node.lang}'>` +
-          highlighted +
-          '</code></pre>';
+
+        if (isJSFlavorSnippet(node)) {
+          const previousNode = parent.children[index - 1] || {};
+          const nextNode = parent.children[index + 1] || {};
+
+          if (node.meta !== 'esm' && node.meta !== 'cjs') {
+            console.warn(
+              `Unknown JavaScript flavor in ${filename}` +
+              `:${node.position.start.line}:${node.position.start.column}`);
+            node.value = `<pre>${highlighted}</pre>`;
+            node.meta = null;
+          } else if (!isJSFlavorSnippet(previousNode) &&
+                     isJSFlavorSnippet(nextNode) &&
+                     nextNode.meta !== node.meta) {
+            node.value = highlighted;
+          } else if (isJSFlavorSnippet(previousNode)) {
+            node.value = '<pre>' +
+              '<input class="js-flavor-selector" type="checkbox"' +
+              (node.meta === 'cjs' ? ' checked' : '') +
+              ' aria-label="Show modern ES modules syntax">' +
+              previousNode.value +
+              highlighted +
+              '</pre>';
+            node.meta = null;
+            previousNode.value = '';
+            previousNode.meta = null;
+          } else {
+            console.warn(
+              `Unused JavaScript flavored block in ${filename}` +
+              `:${node.position.start.line}:${node.position.start.column}`);
+            node.value = `<pre>${highlighted}</pre>`;
+            node.meta = null;
+          }
+        } else {
+          node.value = `<pre>${highlighted}</pre>`;
+        }
       } else if (node.type === 'html' && common.isYAMLBlock(node.value)) {
         node.value = parseYAML(node.value);