Split markdown rendering to a separate package. (#647)

* Introduce the @a2ui/markdown-it package to render markdown across web renderers
* Add some basic types for the markdown renderer in web_core.
* Update the Lit and Angular restaurants sample injecting the new shared renderer.

Author: ditman

.github/CODEOWNERS

@@ -21,6 +21,7 @@
 /renderers/angular/ @ditman @ava-cassiopeia  @crisbeto
 /renderers/lit/ @ditman @ava-cassiopeia @paullewis
 /renderers/web_core/ @ditman @ava-cassiopeia @jacobsimionato
+/renderers/markdown/ @ditman
 
 # Specifications
 /specification/ @gspencergoog @jacobsimionato

.github/workflows/lit_samples_build.yml

@@ -35,21 +35,9 @@ jobs:
         with:
           node-version: '20'
 
-      - name: Install web_core deps
-        working-directory: ./renderers/web_core
-        run: npm ci
-
-      - name: Build web_core
-        working-directory: ./renderers/web_core
-        run: npm run build
-
-      - name: Install lib's deps
-        working-directory: ./renderers/lit
-        run: npm i
-
-      - name: Build lib
-        working-directory: ./renderers/lit
-        run: npm run build
+      - name: Build lit renderer and its dependencies
+        working-directory: ./samples/client/lit
+        run: npm run build:renderer
 
       - name: Install all lit samples workspaces' dependencies
         working-directory: ./samples/client/lit

.github/workflows/ng_build_and_test.yml

@@ -35,34 +35,14 @@ jobs:
         with:
           node-version: '20'
 
-      - name: Install web_core dependencies
-        working-directory: ./renderers/web_core
-        run: npm i
-
-      - name: Build web_core
-        working-directory: ./renderers/web_core
-        run: npm run build
-
-      - name: Install web lib deps
-        working-directory: ./renderers/lit
-        run: npm i
-
-      - name: Build web lib
-        working-directory: ./renderers/lit
-        run: npm run build
-
-      - name: Install renderer deps
-        working-directory: ./renderers/angular
-        run: npm i
-
-      - name: Build Angular renderer
-        working-directory: ./renderers/angular
-        run: npm run build
-
       - name: Install top-level deps
         working-directory: ./samples/client/angular
         run: npm i
 
+      - name: Build Angular renderer and its dependencies
+        working-directory: ./samples/client/angular
+        run: npm run build:renderer
+
       - name: Build contact sample
         working-directory: ./samples/client/angular
         run: npm run build contact

renderers/angular/ng-package.json

@@ -4,5 +4,5 @@
   "lib": {
     "entryFile": "src/public-api.ts"
   },
-  "allowedNonPeerDependencies": ["markdown-it", "@a2ui/web_core"]
+  "allowedNonPeerDependencies": ["@a2ui/web_core"]
 }

renderers/angular/package.json

@@ -7,7 +7,6 @@
   },
   "dependencies": {
     "@a2ui/web_core": "file:../web_core",
-    "markdown-it": "^14.1.0",
     "tslib": "^2.3.0"
   },
   "peerDependencies": {
@@ -23,7 +22,6 @@
     "@angular/core": "^21.2.0",
     "@types/express": "^5.0.1",
     "@types/jasmine": "~5.1.0",
-    "@types/markdown-it": "^14.1.2",
     "@types/node": "^20.17.19",
     "@types/uuid": "^10.0.0",
     "@vitest/browser": "^4.0.15",

renderers/angular/src/lib/catalog/text.ts

@@ -103,8 +103,9 @@ export class Text extends DynamicComponent {
     }
 
     return this.markdownRenderer.render(
-      value,
-      Styles.appendToAll(this.theme.markdown, ['ol', 'ul', 'li'], {}),
+      value, {
+        tagClassMap: Styles.appendToAll(this.theme.markdown, ['ol', 'ul', 'li'], {}),
+      },
     );
   });
 

renderers/angular/src/lib/data/index.ts

@@ -16,3 +16,4 @@
 
 export * from './processor';
 export * from './types';
+export { provideMarkdownRenderer } from './markdown';

renderers/angular/src/lib/data/markdown.ts

@@ -14,101 +14,47 @@
  limitations under the License.
  */
 
-import { inject, Injectable, SecurityContext } from '@angular/core';
+import { inject, Injectable, InjectionToken, SecurityContext } from '@angular/core';
 import { DomSanitizer } from '@angular/platform-browser';
-import MarkdownIt from 'markdown-it';
+import * as Types from '@a2ui/web_core/types/types';
+
+// We need this because Types.MarkdownRenderer is a raw TS type, and can't be used as a token directly.
+const MARKDOWN_RENDERER_TOKEN = new InjectionToken<Types.MarkdownRenderer>('MARKDOWN_RENDERER');
 
 @Injectable({ providedIn: 'root' })
 export class MarkdownRenderer {
-  private originalClassMap = new Map<string, any>();
-  private sanitizer = inject(DomSanitizer);
 
-  private markdownIt = MarkdownIt({
-    highlight: (str, lang) => {
-      if (lang === 'html') {
-        const iframe = document.createElement('iframe');
-        iframe.classList.add('html-view');
-        iframe.srcdoc = str;
-        iframe.sandbox = '';
-        return iframe.innerHTML;
-      }
-
-      return str;
-    },
-  });
+  private markdownRenderer = inject(MARKDOWN_RENDERER_TOKEN, { optional: true });
+  private sanitizer = inject(DomSanitizer);
+  private static defaultMarkdownWarningLogged = false;
 
-  render(value: string, tagClassMap?: Record<string, string[]>) {
-    if (tagClassMap) {
-      this.applyTagClassMap(tagClassMap);
+  render(value: string, markdownOptions?: Types.MarkdownRendererOptions) {
+    if (this.markdownRenderer) {
+      // The markdownRenderer should return a sanitized string.
+      return this.markdownRenderer(value, markdownOptions);
     }
-    const htmlString = this.markdownIt.render(value);
-    this.unapplyTagClassMap();
-    return this.sanitizer.sanitize(SecurityContext.HTML, htmlString);
-  }
-
-  private applyTagClassMap(tagClassMap: Record<string, string[]>) {
-    Object.entries(tagClassMap).forEach(([tag, classes]) => {
-      let tokenName;
-      switch (tag) {
-        case 'p':
-          tokenName = 'paragraph';
-          break;
-        case 'h1':
-        case 'h2':
-        case 'h3':
-        case 'h4':
-        case 'h5':
-        case 'h6':
-          tokenName = 'heading';
-          break;
-        case 'ul':
-          tokenName = 'bullet_list';
-          break;
-        case 'ol':
-          tokenName = 'ordered_list';
-          break;
-        case 'li':
-          tokenName = 'list_item';
-          break;
-        case 'a':
-          tokenName = 'link';
-          break;
-        case 'strong':
-          tokenName = 'strong';
-          break;
-        case 'em':
-          tokenName = 'em';
-          break;
-      }
-
-      if (!tokenName) {
-        return;
-      }
 
-      const key = `${tokenName}_open`;
-      const original = this.markdownIt.renderer.rules[key];
-      this.originalClassMap.set(key, original);
-
-      this.markdownIt.renderer.rules[key] = (tokens, idx, options, env, self) => {
-        const token = tokens[idx];
-        for (const clazz of classes) {
-          token.attrJoin('class', clazz);
-        }
-
-        if (original) {
-          return original.call(this, tokens, idx, options, env, self);
-        } else {
-          return self.renderToken(tokens, idx, options);
-        }
-      };
-    });
-  }
-
-  private unapplyTagClassMap() {
-    for (const [key, original] of this.originalClassMap) {
-      this.markdownIt.renderer.rules[key] = original;
+    if (!MarkdownRenderer.defaultMarkdownWarningLogged) {
+      console.warn("[MarkdownRenderer]",
+        "can't render markdown because no markdown renderer is configured.\n",
+        "Use `@a2ui/markdown-it`, or your own markdown renderer.");
+      MarkdownRenderer.defaultMarkdownWarningLogged = true;
     }
 
-    this.originalClassMap.clear();
+    // Return a span with a sanitized version of the input `value`.
+    const sanitizedValue = this.sanitizer.sanitize(SecurityContext.HTML, value);
+    return `<span class="no-markdown-renderer">${sanitizedValue}</span>`;
   }
 }
+
+/**
+ * Allows the user to provide a markdown renderer function.
+ * @param {Types.MarkdownRenderer} markdownRenderer a markdown renderer function.
+ * @returns an Angular provider for the markdown renderer.
+ */
+export function provideMarkdownRenderer(markdownRenderer: Types.MarkdownRenderer) {
+  return {
+    provide: MARKDOWN_RENDERER_TOKEN,
+    useValue: markdownRenderer,
+  };
+}