wc-compiler 0.1.0

package/README.md

@@ -0,0 +1,106 @@
+# wcc
+
+[![Netlify Status](https://api.netlify.com/api/v1/badges/e718eac2-b3bc-4986-8569-49706a430beb/deploy-status)](https://app.netlify.com/sites/merry-caramel-524e61/deploys)
+[![GitHub release](https://img.shields.io/github/tag/thescientist13/wcc.svg)](https://github.com/thescientist13/wcc/tags)
+![GitHub Actions status](https://github.com/thescientist13/wcc/workflows/Master%20Integration/badge.svg)
+[![GitHub issues](https://img.shields.io/github/issues-pr-raw/thescientist13/wcc.svg)](https://github.com/thescientist13/wcc/issues)
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/thescientist13/wcc/master/LICENSE.md)
+
+Experimental native Web Components compiler. (`<w⚙️⚙️/>`)
+
+> _It's Web Components all the way down._  🐢
+
+## Overview
+
+**Web Components Compiler (WCC)** is a NodeJS package designed to make server-side rendering (SSR) of native Web Components easier.  It can render (within reason 😅) your Web Component into static HTML leveraging [Declarative Shadow DOM](https://web.dev/declarative-shadow-dom/).
+
+It is not a static site generator or framework.  It is focused on producing raw HTML from Web Components with the intent of being easily _integrated_ into a site generator or framework.  
+
+> _The original motivation for this project was to create a [purpose built, lighter weight, alternative to puppeteer for SSR of `HTMLElement`](https://github.com/ProjectEvergreen/greenwood/issues/926) for the project [**Greenwood**](https://www.greenwoodjs.io/)._
+
+In addition, WCC hopes to provide a surface area to explore patterns around [streaming](https://github.com/thescientist13/wcc/issues/5) and serverless rendering, as well as acting as a test bed for the [Web Components Community Groups](https://github.com/webcomponents-cg) discussions around community protocols, like [hydration](https://github.com/thescientist13/wcc/issues/3). 
+
+## Key Features
+
+1. Supports the following `HTMLElement` lifecycles and methods on the server side
+    - `constructor`
+    - `connectedCallback`
+    - `attachShadow`
+    - `innerHTML`
+    - `[get|set|has]Attribute`
+1. Recursive rendering of nested custom elements
+1. Optional Declarative Shadow DOM (for producing purely content driven static pages)
+1. Metadata and runtime hints to support progressive hydration and lazy loading strategies
+
+## Installation
+
+**wcc** can be installed from npm.
+
+```shell
+$ npm install wc-compiler --save-dev
+```
+
+## Usage
+
+WCC exposes a few utilities to render your Web Components.  Below is one example, with [full docs and more examples](https://wcc.greenwoodjs.io) available on the website.
+
+1. Given a custom element like so:
+    ```js
+    const template = document.createElement('template');
+
+    template.innerHTML = `
+      <style>
+        .footer {
+          color: white;
+          background-color: #192a27;
+        }
+      </style>
+
+      <footer class="footer">
+        <h4>My Blog &copy; ${new Date().getFullYear()}</h4>
+      </footer>
+    `;
+
+    class Footer extends HTMLElement {
+      connectedCallback() {
+        if (!this.shadowRoot) {
+          this.attachShadow({ mode: 'open' });
+          this.shadowRoot.appendChild(template.content.cloneNode(true));
+        }
+      }
+    }
+
+    export default Footer;
+
+    customElements.define('wcc-footer', Footer);
+    ```
+
+1. Using NodeJS, create a file that imports `renderToString` and provide it the path to your web component
+    ```js
+    import { renderToString } from 'wc-compiler';
+
+    const { html } = renderToString(new URL('./path/to/footer.js', import.meta.url));
+
+    console.debug({ html })
+    ```
+
+1. You will get the following html output that can be used in conjunction with your preferred site framework or templating solution.
+    ```html
+    <wcc-footer>
+      <template shadowroot="open">
+        <style>
+          .footer {
+            color: white;
+            background-color: #192a27;
+          }
+        </style>
+
+        <footer class="footer">
+          <h4>My Blog &copy; 2022</h4>
+        </footer>
+      </template>
+    </wcc-footer>
+    ```
+
+
+> _**Make sure to test in Chrome, or other Declarative Shadow DOM compatible browser, otherwise you will need to include the [DSD polyfill](https://web.dev/declarative-shadow-dom/#polyfill).**_

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "wc-compiler",
+  "version": "0.1.0",
+  "description": "Experimental native Web Components compiler.",
+  "main": "src/wcc.js",
+  "type": "module",
+  "author": "Owen Buckley <owen@thegreenhouse.io>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14"
+  },
+  "files": [
+    "src/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "lint": "eslint \"*.*js\" \"./src/**/**/*.js\" \"./test/**/**/*.js\"",
+    "develop": "concurrently \"nodemon --watch src --watch docs -e js,md,css,html ./build.js\" \"http-server ./dist --open\"",
+    "build": "node ./build.js",
+    "serve": "node ./build.js && http-server ./dist --open",
+    "example:ssg": "node ./examples/ssg.js",
+    "example:ssr": "node ./examples/ssr.js",
+    "start": "npm run develop",
+    "test": "c8 mocha --parallel",
+    "test:tdd": "npm run test --watch"
+  },
+  "dependencies": {
+    "acorn": "^8.7.0",
+    "acorn-walk": "^8.2.0",
+    "parse5": "^6.0.1"
+  },
+  "devDependencies": {
+    "@mapbox/rehype-prism": "^0.8.0",
+    "c8": "^7.11.2",
+    "chai": "^4.3.6",
+    "concurrently": "^7.1.0",
+    "eslint": "^8.14.0",
+    "http-server": "^14.1.0",
+    "jsdom": "^19.0.0",
+    "mocha": "^9.2.2",
+    "nodemon": "^2.0.15",
+    "prismjs": "^1.28.0",
+    "simple.css": "^0.1.3",
+    "rehype-raw": "^6.1.1",
+    "rehype-stringify": "^9.0.3",
+    "remark-parse": "^10.0.1",
+    "remark-rehype": "^10.1.0",
+    "unified": "^10.1.2"
+  }
+}

package/src/dom-shim.js

@@ -0,0 +1,141 @@
+// https://developer.mozilla.org/en-US/docs/Web/API/EventTarget
+class EventTarget { }
+
+// https://developer.mozilla.org/en-US/docs/Web/API/Node
+// EventTarget <- Node
+class Node extends EventTarget {
+  constructor() {
+    super();
+    // console.debug('Node constructor');
+  }
+
+  // eslint-disable-next-line
+  cloneNode(deep) {
+    return this;
+  }
+
+  appendChild(node) {
+    this.innerHTML = this.innerHTML ? this.innerHTML += node.textContent : node.textContent;
+  }
+}
+
+// https://developer.mozilla.org/en-US/docs/Web/API/Element
+// EventTarget <- Node <- Element
+class Element extends Node {
+  constructor() {
+    super();
+    // console.debug('Element constructor');
+    this.shadowRoot = null;
+    this.innerHTML;
+    this.attributes = {};
+  }
+
+  setAttribute(name, value) {
+    this.attributes[name] = value;
+  }
+
+  getAttribute(name) {
+    return this.attributes[name];
+  }
+
+  hasAttribute(name) {
+    return !!this.attributes[name];
+  }
+}
+
+// https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement
+// EventTarget <- Node <- Element <- HTMLElement
+class HTMLElement extends Element {
+  constructor() {
+    super();
+    // console.debug('HTMLElement::constructor');
+  }
+
+  attachShadow(options) {
+    // console.debug('HTMLElement::attachShadow');
+    this.shadowRoot = new ShadowRoot(options);
+
+    return this.shadowRoot;
+  }
+
+  connectedCallback() {
+    // console.debug('HTMLElement::connectedCallback');
+  }
+
+  // https://github.com/mfreed7/declarative-shadow-dom/blob/master/README.md#serialization
+  getInnerHTML(options = {}) {
+    return options.includeShadowRoots
+      ? `
+        <template shadowroot="${this.shadowRoot.mode}">
+          ${this.shadowRoot.innerHTML}
+        </template>
+      `
+      : this.shadowRoot.innerHTML;
+  }
+}
+
+// https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment
+// EventTarget <- Node <- DocumentFragment
+class DocumentFragment extends Node {
+  // eslint-disable-next-line
+  constructor(contents) {
+    super();
+    // console.debug('DocumentFragment constructor', contents);
+  }
+}
+
+// https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot
+// EventTarget <- Node <- DocumentFragment <- ShadowRoot
+class ShadowRoot extends DocumentFragment {
+  constructor(options) {
+    super();
+    // console.debug('ShadowRoot constructor');
+    this.mode = options.mode || 'closed';
+  }
+}
+
+// https://developer.mozilla.org/en-US/docs/Web/API/HTMLTemplateElement
+// EventTarget <- Node <- Element <- HTMLElement <- HTMLTemplateElement
+class HTMLTemplateElement extends HTMLElement {
+  constructor() {
+    super();
+    // console.debug('HTMLTemplateElement constructor');
+
+    this.content = new DocumentFragment(this.innerHTML);
+  }
+
+  set innerHTML(html) {
+    this.content.textContent = html;
+  }
+}
+
+const customElementsRegistry = {};
+
+globalThis.document = {
+  createElement(tagName) {
+    switch (tagName) {
+
+      case 'template':
+        return new HTMLTemplateElement();
+
+      default:
+        return new HTMLElement();
+
+    }
+  },
+  createDocumentFragment(html) {
+    return new DocumentFragment(html);
+  }
+};
+
+globalThis.HTMLElement = HTMLElement;
+globalThis.customElements = {
+  define: (tagName, BaseClass) => {
+    // console.debug('customElements.define => ', tagName);
+    customElementsRegistry[tagName] = BaseClass;
+  },
+  get: (tagName) => {
+    // console.debug('customElements.get => ', tagName);
+    return customElementsRegistry[tagName];
+  }
+};

package/src/wcc.js

@@ -0,0 +1,130 @@
+// this must come first
+import './dom-shim.js';
+
+import * as acorn from 'acorn';
+import * as walk from 'acorn-walk';
+import { parse, parseFragment, serialize } from 'parse5';
+
+import fs from 'node:fs/promises';
+
+let definitions;
+
+async function renderComponentRoots(tree, includeShadowRoots = true) {
+  for (const node of tree.childNodes) {
+    if (node.tagName && node.tagName.indexOf('-') > 0) {
+      const { tagName } = node;
+      const { moduleURL } = definitions[tagName];
+      const elementInstance = await initializeCustomElement(moduleURL, tagName, node.attrs);
+
+      const shadowRootHtml = elementInstance.getInnerHTML({ includeShadowRoots });
+      const shadowRootTree = parseFragment(shadowRootHtml);
+
+      node.childNodes = node.childNodes.length === 0 ? shadowRootTree.childNodes : [...shadowRootTree.childNodes, ...node.childNodes];
+    }
+
+    if (node.childNodes && node.childNodes.length > 0) {
+      await renderComponentRoots(node, includeShadowRoots);
+    }
+
+    // does this only apply to `<template>` tags?
+    if (node.content && node.content.childNodes && node.content.childNodes.length > 0) {
+      await renderComponentRoots(node.content, includeShadowRoots);
+    }
+  }
+
+  return tree;
+}
+
+async function registerDependencies(moduleURL) {
+  const moduleContents = await fs.readFile(moduleURL, 'utf-8');
+
+  walk.simple(acorn.parse(moduleContents, {
+    ecmaVersion: 'latest',
+    sourceType: 'module'
+  }), {
+    async ImportDeclaration(node) {
+      const dependencyModuleURL = new URL(node.source.value, moduleURL);
+
+      await registerDependencies(dependencyModuleURL);
+    },
+    async ExpressionStatement(node) {
+      const { expression } = node;
+
+      if (expression.type === 'CallExpression' && expression.callee && expression.callee.object
+        && expression.callee.property && expression.callee.object.name === 'customElements'
+        && expression.callee.property.name === 'define') {
+
+        const tagName = node.expression.arguments[0].value;
+
+        definitions[tagName] = {
+          instanceName: node.expression.arguments[1].name,
+          moduleURL
+        };
+      }
+    }
+  });
+}
+
+async function initializeCustomElement(elementURL, tagName, attrs = []) {
+  await registerDependencies(elementURL);
+
+  const element = tagName
+    ? customElements.get(tagName)
+    : (await import(elementURL)).default;
+  const dataLoader = (await import(elementURL)).getData;
+  const data = dataLoader ? await dataLoader() : {};
+  const elementInstance = new element(data); // eslint-disable-line new-cap
+
+  attrs.forEach((attr) => {
+    elementInstance.setAttribute(attr.name, attr.value);
+
+    if (attr.name === 'hydrate') {
+      definitions[tagName].hydrate = attr.value;
+    }
+  });
+
+  await elementInstance.connectedCallback();
+
+  return elementInstance;
+}
+
+async function renderToString(elementURL, options = {}) {
+  definitions = [];
+
+  const { lightMode = false } = options;
+  const includeShadowRoots = !lightMode;
+
+  const elementInstance = await initializeCustomElement(elementURL);
+  const elementHtml = elementInstance.getInnerHTML({ includeShadowRoots });
+  const elementTree = parseFragment(elementHtml);
+  const finalTree = await renderComponentRoots(elementTree, includeShadowRoots);
+
+  return {
+    html: serialize(finalTree),
+    metadata: definitions
+  };
+}
+
+async function renderFromHTML(html, elements = [], options = {}) {
+  definitions = [];
+
+  const { lightMode = false } = options;
+  const includeShadowRoots = !lightMode;
+
+  for (const url of elements) {
+    await initializeCustomElement(url);
+  }
+
+  const elementTree = parse(html);
+  const finalTree = await renderComponentRoots(elementTree, includeShadowRoots);
+
+  return {
+    html: serialize(finalTree),
+    metadata: definitions
+  };
+}
+
+export {
+  renderToString,
+  renderFromHTML
+};