feat(mdjs-preview): provide overridable renderFunction

Author: tlouisse

.changeset/tiny-ties-press.md

@@ -0,0 +1,5 @@
+---
+'@mdjs/mdjs-preview': patch
+---
+
+add overridable `renderFunction` to mdjs-preview

docs/docs/markdown-javascript/preview.md

@@ -226,6 +226,33 @@ class DemoElement extends HTMLElement {
 customElements.define('demo-element', DemoElement);
 ```
 
+## Extending mdjs-preview
+
+It is possible to define a custom version of mdjs-preview in order to add functionality, change
+its appearance of make it run in 'hybrid mode' (accepting both lit1 and -2 TemplateResults).
+The example below shows how the latter can be achieved by providing a custom render function.
+Note that we define `mdjs-preview` as the custom element name. We need to make sure that this
+file is executed before the original mdjs-preview definition file is executed.
+
+```js
+import { MdJsPreview } from '@mdjs/mdjs-preview';
+import { render as render2 } from 'lit';
+import { isTemplateResult as isTemplateResult2 } from 'lit/directive-helpers.js';
+import { render as render1  } from 'lit-html';
+
+export class HybridLitMdjsPreview extends MdJsPreview {
+  get renderFunction() {
+    return function renderHybrid(html, container, options) {
+        if (isTemplateResult2(html)) {
+          render2(html, container, options);
+        } else {
+          render1(html, container, options);
+        }
+    };
+  }
+customElements.define('mdjs-preview', HybridLitMdjsPreview);
+```
+
 ```js script
 import '@rocket/launch/inline-notification/inline-notification.js';
 ```

package.json

@@ -33,7 +33,6 @@
     "setup": "npm run setup:ts-configs && npm run build:packages",
     "setup:patches": "npx patch-package",
     "setup:ts-configs": "node scripts/generate-ts-configs.mjs",
-    "xprestart": "yarn analyze",
     "start": "node --trace-warnings packages/cli/src/cli.js start",
     "test": "yarn test:node && yarn test:web",
     "test:node": "mocha \"packages/*/test-node/**/*.test.{ts,js,mjs,cjs}\" --timeout 5000 --reporter dot --exit",
@@ -44,12 +43,13 @@
     "types:copy": "node scripts/workspaces-scripts-bin.mjs types:copy",
     "update-dependency": "node scripts/update-dependency.js",
     "update-esm-entrypoints": "node scripts/update-esm-entrypoints.mjs && yarn format",
-    "update-package-configs": "node scripts/update-package-configs.mjs && yarn format"
+    "update-package-configs": "node scripts/update-package-configs.mjs && yarn format",
+    "xprestart": "yarn analyze"
   },
   "devDependencies": {
     "@changesets/cli": "^2.20.0",
     "@custom-elements-manifest/analyzer": "^0.4.12",
-    "@open-wc/testing": "^3.0.0-next.1",
+    "@open-wc/testing": "^3.1.2",
     "@rollup/plugin-commonjs": "^17.0.0",
     "@rollup/plugin-json": "^4.1.0",
     "@rollup/plugin-typescript": "^8.1.0",

packages/mdjs-preview/src/MdJsPreview.js

@@ -72,6 +72,38 @@ export class MdJsPreview extends ScopedElementsMixin(LitElement) {
     };
   }
 
+  /**
+   * By default, the render of lit2 is provided, which is compatible with TemplateResults of lit2.
+   * However, in contexts that need to run multiple versions of lit, it should be possible to
+   * provide a specific render function, like renderHybrid, that internally checks, based on the
+   * TemplateResult, whether the render function of lit 1 or 2 should called.
+   * Overriding the render function would look like:
+   *
+   * @example
+   * ```js
+   * import { MdJsPreview } from '@mdjs/mdjs-preview';
+   * import { render as render2 } from 'lit';
+   * import { isTemplateResult as isTemplateResult2 } from 'lit/directive-helpers.js';
+   * import { render as render1  } from 'lit-html';
+   *
+   * export class HybridLitMdjsPreview extends MdJsPreview {
+   *   get renderFunction() {
+   *     return function renderHybrid(html, container, options) {
+   *        if (isTemplateResult2(html)) {
+   *          render2(html, container, options);
+   *        } else {
+   *          render1(html, container, options);
+   *        }
+   *     };
+   *   }
+   * }
+   * customElements.define('mdjs-preview', HybridLitMdjsPreview);
+   * ```
+   */
+  get renderFunction() {
+    return render;
+  }
+
   constructor() {
     super();
     /** @type {LitHtmlStoryFn} */
@@ -257,7 +289,7 @@ export class MdJsPreview extends ScopedElementsMixin(LitElement) {
     }
 
     if (this.lightDomRenderTarget && changeProps.has('story')) {
-      render(this.story({ shadowRoot: this }), this.lightDomRenderTarget);
+      this.renderFunction(this.story({ shadowRoot: this }), this.lightDomRenderTarget);
     }
 
     if (changeProps.has('platform') || changeProps.has('size')) {

packages/mdjs-preview/test-web/mdjs-preview.subclasser.test.js

@@ -0,0 +1,32 @@
+import { expect, fixture, html } from '@open-wc/testing';
+import { html as storyHtml } from '@mdjs/mdjs-preview';
+import { MdJsPreview } from '@mdjs/mdjs-preview';
+import { render as render2 } from 'lit';
+import { isTemplateResult as isTemplateResult2 } from 'lit/directive-helpers.js';
+
+/** @typedef {import('@mdjs/mdjs-preview').MdJsPreview} MdJsPreview */
+
+describe('mdjs-preview Subclasser', () => {
+  it('will expose a render function getter to override in extensions', async () => {
+    let isCalled = false;
+    class HybridLitMdjsPreview extends MdJsPreview {
+      get renderFunction() {
+        return function renderStrict(html, container, options) {
+          isCalled = true;
+          if (isTemplateResult2(html)) {
+            render2(html, container, options);
+          } else {
+            throw new Error('[mdjs-preview]: Only lit2 allowed');
+          }
+        };
+      }
+    }
+    customElements.define('mdjs-preview', HybridLitMdjsPreview);
+
+    const el = await fixture(html`
+      <mdjs-preview .story=${() => storyHtml`<p id="testing"></p>`}></mdjs-preview>
+    `);
+    expect(isCalled).to.be.true;
+    expect(el.querySelectorAll('#testing').length).to.equal(1);
+  });
+});

packages/mdjs-preview/test-web/mdjs-preview.test.js

@@ -5,7 +5,7 @@ import '@mdjs/mdjs-preview/define';
 /** @typedef {import('@mdjs/mdjs-preview').MdJsPreview} MdJsPreview */
 
 describe('mdjs-preview', () => {
-  it('will render the element into the shadow root by default', async () => {
+  it('will render the element into light dom by default', async () => {
     const el = await fixture(html`
       <mdjs-preview .story=${() => storyHtml`<p id="testing"></p>`}></mdjs-preview>
     `);