feat(runtime): export a render method from the runtime (#6245)

* feat(runtime): export a render method

* fix unit tests

* add missing export

Author: christian-bromann

package.json

@@ -64,7 +64,8 @@
     },
     "./compiler/*": {
       "types": "./compiler/*",
-      "import": "./compiler/*"
+      "import": "./compiler/*",
+      "require": "./compiler/*"
     },
     "./screenshot": {
       "types": "./screenshot/index.d.ts",

src/compiler/output-targets/dist-custom-elements/index.ts

@@ -255,7 +255,7 @@ export const generateEntryPoint = (
 
   // Exports that are always present
   exports.push(
-    `export { getAssetPath, setAssetPath, setNonce, setPlatformOptions } from '${STENCIL_INTERNAL_CLIENT_ID}';`,
+    `export { getAssetPath, setAssetPath, setNonce, setPlatformOptions, render } from '${STENCIL_INTERNAL_CLIENT_ID}';`,
     `export * from '${USER_INDEX_ENTRY_ID}';`,
   );
 

src/compiler/output-targets/test/output-targets-dist-custom-elements.spec.ts

@@ -72,7 +72,7 @@ describe('Custom Elements output target', () => {
       });
 
       expect(entryPoint).toEqual(`import { globalScripts } from '${STENCIL_APP_GLOBALS_ID}';
-export { getAssetPath, setAssetPath, setNonce, setPlatformOptions } from '${STENCIL_INTERNAL_CLIENT_ID}';
+export { getAssetPath, setAssetPath, setNonce, setPlatformOptions, render } from '${STENCIL_INTERNAL_CLIENT_ID}';
 export * from '${USER_INDEX_ENTRY_ID}';
 
 globalScripts();
@@ -86,7 +86,7 @@ globalScripts();
       });
 
       expect(entryPoint)
-        .toEqual(`export { getAssetPath, setAssetPath, setNonce, setPlatformOptions } from '${STENCIL_INTERNAL_CLIENT_ID}';
+        .toEqual(`export { getAssetPath, setAssetPath, setNonce, setPlatformOptions, render } from '${STENCIL_INTERNAL_CLIENT_ID}';
 export * from '${USER_INDEX_ENTRY_ID}';
 `);
     });
@@ -164,7 +164,7 @@ export * from '${USER_INDEX_ENTRY_ID}';
         addCustomElementInputs(buildCtx, bundleOptions, config.outputTargets[0] as OutputTargetDistCustomElements);
         expect(bundleOptions.loader['\0core']).toEqual(
           `import { globalScripts } from '${STENCIL_APP_GLOBALS_ID}';
-export { getAssetPath, setAssetPath, setNonce, setPlatformOptions } from '${STENCIL_INTERNAL_CLIENT_ID}';
+export { getAssetPath, setAssetPath, setNonce, setPlatformOptions, render } from '${STENCIL_INTERNAL_CLIENT_ID}';
 export * from '${USER_INDEX_ENTRY_ID}';
 
 globalScripts();
@@ -197,7 +197,7 @@ globalScripts();
         addCustomElementInputs(buildCtx, bundleOptions, config.outputTargets[0] as OutputTargetDistCustomElements);
         expect(bundleOptions.loader['\0core']).toEqual(
           `import { globalScripts } from '${STENCIL_APP_GLOBALS_ID}';
-export { getAssetPath, setAssetPath, setNonce, setPlatformOptions } from '${STENCIL_INTERNAL_CLIENT_ID}';
+export { getAssetPath, setAssetPath, setNonce, setPlatformOptions, render } from '${STENCIL_INTERNAL_CLIENT_ID}';
 export * from '${USER_INDEX_ENTRY_ID}';
 export { StubCmp, defineCustomElement as defineCustomElementStubCmp } from '\0StubCmp';
 export { MyBestComponent, defineCustomElement as defineCustomElementMyBestComponent } from '\0MyBestComponent';
@@ -224,7 +224,7 @@ globalScripts();
         addCustomElementInputs(buildCtx, bundleOptions, config.outputTargets[0] as OutputTargetDistCustomElements);
         expect(bundleOptions.loader['\0core']).toEqual(
           `import { globalScripts } from '${STENCIL_APP_GLOBALS_ID}';
-export { getAssetPath, setAssetPath, setNonce, setPlatformOptions } from '${STENCIL_INTERNAL_CLIENT_ID}';
+export { getAssetPath, setAssetPath, setNonce, setPlatformOptions, render } from '${STENCIL_INTERNAL_CLIENT_ID}';
 export * from '${USER_INDEX_ENTRY_ID}';
 export { ComponentWithJsx, defineCustomElement as defineCustomElementComponentWithJsx } from '\0ComponentWithJsx';
 
@@ -259,7 +259,7 @@ globalScripts();
           `import { globalScripts } from '${STENCIL_APP_GLOBALS_ID}';
 import { StubCmp } from '\0StubCmp';
 import { MyBestComponent } from '\0MyBestComponent';
-export { getAssetPath, setAssetPath, setNonce, setPlatformOptions } from '${STENCIL_INTERNAL_CLIENT_ID}';
+export { getAssetPath, setAssetPath, setNonce, setPlatformOptions, render } from '${STENCIL_INTERNAL_CLIENT_ID}';
 export * from '${USER_INDEX_ENTRY_ID}';
 
 globalScripts();

src/declarations/stencil-public-runtime.ts

@@ -302,6 +302,26 @@ export declare function setPlatformHelpers(helpers: {
  */
 export declare function getAssetPath(path: string): string;
 
+/**
+ * Method to render a virtual DOM tree to a container element.
+ *
+ * @example
+ * ```tsx
+ * import { render } from '@stencil/core';
+ *
+ * const vnode = (
+ *   <div>
+ *     <h1>Hello, world!</h1>
+ *   </div>
+ * );
+ * render(vnode, document.body);
+ * ```
+ *
+ * @param vnode - The virtual DOM tree to render
+ * @param container - The container element to render the virtual DOM tree to
+ */
+export declare function render(vnode: VNode, container: Element): void;
+
 /**
  * Used to manually set the base path where assets can be found. For lazy-loaded
  * builds the asset path is automatically set and assets copied to the correct

src/internal/stencil-core/index.d.ts

@@ -41,6 +41,7 @@ export {
   Method,
   Prop,
   readTask,
+  render,
   setAssetPath,
   setErrorHandler,
   setMode,

src/internal/stencil-core/index.js

@@ -1,16 +1,17 @@
 export {
   Build,
+  forceUpdate,
   getAssetPath,
   getElement,
   getMode,
   getRenderingRef,
-  forceUpdate,
   h,
   Host,
   readTask,
-  setMode,
+  render,
   setAssetPath,
+  setErrorHandler,
+  setMode,
   setPlatformHelpers,
   writeTask,
-  setErrorHandler,
 } from '../client/index.js';

src/runtime/index.ts

@@ -12,6 +12,7 @@ export { setNonce } from './nonce';
 export { parsePropertyValue } from './parse-property-value';
 export { setPlatformOptions } from './platform-options';
 export { proxyComponent } from './proxy-component';
+export { render } from './render';
 export { getValue, setValue } from './set-value';
 export { forceUpdate, getRenderingRef, postUpdateComponent } from './update-component';
 export { h, Host } from './vdom/h';

src/runtime/render.ts

@@ -0,0 +1,35 @@
+import type * as d from '../declarations';
+import { renderVdom } from './vdom/vdom-render';
+
+/**
+ * Method to render a virtual DOM tree to a container element.
+ *
+ * @example
+ * ```tsx
+ * import { render } from '@stencil/core';
+ *
+ * const vnode = (
+ *   <div>
+ *     <h1>Hello, world!</h1>
+ *   </div>
+ * );
+ * render(vnode, document.body);
+ * ```
+ *
+ * @param vnode - The virtual DOM tree to render
+ * @param container - The container element to render the virtual DOM tree to
+ */
+export function render(vnode: d.VNode, container: Element) {
+  const cmpMeta: d.ComponentRuntimeMeta = {
+    $flags$: 0,
+    $tagName$: container.tagName,
+  };
+
+  const ref: d.HostRef = {
+    $flags$: 0,
+    $cmpMeta$: cmpMeta,
+    $hostElement$: container as d.HostElement,
+  };
+
+  renderVdom(ref, vnode);
+}

test/wdio/render/render.test.tsx

@@ -0,0 +1,54 @@
+import { h, render } from '@stencil/core';
+import { $, expect } from '@wdio/globals';
+
+import { defineCustomElement } from '../test-components/complex-properties.js';
+
+describe('Render VDOM', () => {
+  beforeEach(async () => {
+    document.querySelector('div')?.remove();
+  });
+
+  it('can render an arbitrary VDOM tree', async () => {
+    const vdom = h('div', { className: 'test' }, 'Hello, world!');
+    render(vdom, document.body);
+
+    await expect($(document.body).$('div')).toMatchInlineSnapshot(`"<div class="test">Hello, world!</div>"`);
+  });
+
+  it('can render a VDOM with a Stencil component', async () => {
+    defineCustomElement();
+
+    const vdom = (
+      <div>
+        <complex-properties
+          foo={{ bar: 123, loo: [1, 2, 3], qux: { quux: Symbol('quux') } }}
+          baz={new Map([['foo', { qux: Symbol('quux') }]])}
+          quux={new Set(['foo'])}
+          corge={new Set([{ foo: { bar: 'foo' } }])}
+          grault={Infinity}
+          waldo={null}
+          kidsNames={['John', 'Jane', 'Jim']}
+        ></complex-properties>
+      </div>
+    );
+    render(vdom, document.body);
+    await expect($(document.body).$('div')).toMatchInlineSnapshot(`
+      "<div>
+        <complex-properties class="hydrated">
+          <template shadowrootmode="open">
+            <ul>
+              <li>this.foo.bar: 123</li>
+              <li>this.foo.loo: 1, 2, 3</li>
+              <li>this.foo.qux: symbol</li>
+              <li>this.baz.get('foo'): symbol</li>
+              <li>this.quux.has('foo'): true</li>
+              <li>this.grault: true</li>
+              <li>this.waldo: true</li>
+              <li>this.kidsNames: John, Jane, Jim</li>
+            </ul>
+          </template>
+        </complex-properties>
+      </div>"
+    `);
+  });
+});

test/wdio/scoped-id-in-nested-classname/cmp.test.tsx

@@ -1,9 +1,11 @@
 import { h } from '@stencil/core';
 import { render } from '@wdio/browser-runner/stencil';
+import { $, expect } from '@wdio/globals';
 
 describe('scope-id-in-nested-classname', function () {
   it('should have root scope id in the nested element as classname', async () => {
     render({
+      components: [],
       template: () => <cmp-level-1></cmp-level-1>,
     });
     await $('cmp-level-3').waitForStable();
@@ -19,6 +21,7 @@ describe('scope-id-in-nested-classname', function () {
 
   it('should not have root scope id in slotted / user provided nested element as classname', async () => {
     render({
+      components: [],
       template: () => (
         <cmp-level-1>
           <span id="test-element">Test</span>

test/wdio/setup.ts

@@ -17,7 +17,8 @@ const testRequiresManualSetup =
   window.__wdioSpec__.includes('global-script') ||
   window.__wdioSpec__.endsWith('custom-tag-name.test.tsx') ||
   window.__wdioSpec__.endsWith('page-list.test.ts') ||
-  window.__wdioSpec__.endsWith('event-re-register.test.tsx');
+  window.__wdioSpec__.endsWith('event-re-register.test.tsx') ||
+  window.__wdioSpec__.endsWith('render.test.tsx');
 
 /**
  * setup all components defined in tests except for those where we want to manually setup