wc-compiler 0.2.0 → 0.3.0

package/README.md

@@ -1,44 +1,17 @@
-# wcc
-
 <img src="https://merry-caramel-524e61.netlify.app/assets/wcc-logo.png" width="30%"/>
 
-> _Experimental Web Components compiler.  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
+# Web Components Compiler (WCC)
 
-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
-```
+[![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/ProjectEvergreen/wcc.svg)](https://github.com/ProjectEvergreen/wcc/tags)
+![GitHub Actions status](https://github.com/ProjectEvergreen/wcc/workflows/Master%20Integration/badge.svg)
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/ProjectEvergreen/wcc/master/LICENSE.md)
 
-## Usage
+> _Experimental Web Components compiler.  It's Web Components all the way down!_  🐢
 
-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.
+## How It Works
 
-1. Given a custom element like so:
+1. Write a Web Component
     ```js
     const template = document.createElement('template');
 
@@ -68,17 +41,13 @@ WCC exposes a few utilities to render your Web Components.  Below is one example
 
     customElements.define('wcc-footer', Footer);
     ```
-
-1. Using NodeJS, create a file that imports `renderToString` and provide it the path to your web component
+1. Run it through the compiler
     ```js
     import { renderToString } from 'wc-compiler';
 
-    const { html } = await renderToString(new URL('./path/to/footer.js', import.meta.url));
-
-    console.debug({ html })
+    const { html } = await renderToString(new URL('./path/to/component.js', import.meta.url));
     ```
-
-1. You will get the following HTML output that can be used in conjunction with your preferred site framework or templating solution.
+1. Get HTML!
     ```html
     <wcc-footer>
       <template shadowroot="open">
@@ -96,5 +65,20 @@ WCC exposes a few utilities to render your Web Components.  Below is one example
     </wcc-footer>
     ```
 
+## Installation
+
+**WCC** runs on NodeJS and can be installed from npm.
+
+```shell
+$ npm install wc-compiler --save-dev
+```
+
+## Documentation
+
+See our [website](https://merry-caramel-524e61.netlify.app/) for API docs and examples.
+
+## Motivation
+
+**WCC** is not a static site generator, framework or bundler.  It is focused on producing raw HTML from Web Components with the intent of being easily integrated into a site generator or framework, like [**Greenwood**](https://github.com/ProjectEvergreen/greenwood/), the original motivation for creating [this project](https://github.com/ProjectEvergreen/greenwood/issues/935).
 
-> _**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).**_
+In addition, **WCC** hopes to provide a surface area to explore patterns around [streaming](https://github.com/ProjectEvergreen/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/ProjectEvergreen/wcc/issues/3).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wc-compiler",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Experimental native Web Components compiler.",
   "main": "src/wcc.js",
   "type": "module",
@@ -42,11 +42,14 @@
     "mocha": "^9.2.2",
     "nodemon": "^2.0.15",
     "prismjs": "^1.28.0",
-    "simple.css": "^0.1.3",
+    "rehype-autolink-headings": "^6.1.1",
     "rehype-raw": "^6.1.1",
+    "rehype-slug": "^5.0.1",
     "rehype-stringify": "^9.0.3",
     "remark-parse": "^10.0.1",
     "remark-rehype": "^10.1.0",
+    "remark-toc": "^8.0.1",
+    "simple.css": "^0.1.3",
     "unified": "^10.1.2"
   }
 }

package/src/wcc.js

@@ -10,7 +10,7 @@ import fs from 'node:fs/promises';
 let definitions;
 
 function getParse(html) {
-  return html.indexOf('<html>') >= 0 || html.indexOf('<body>') || html.indexOf('<head>')
+  return html.indexOf('<html>') >= 0 || html.indexOf('<body>') >= 0 || html.indexOf('<head>') >= 0
     ? parse
     : parseFragment;
 }
@@ -23,26 +23,29 @@ function isCustomElementDefinitionNode(node) {
     && expression.callee.property.name === 'define';
 }
 
-async function renderComponentRoots(tree, includeShadowRoots = true) {
+async function renderComponentRoots(tree) {
   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];
+      const elementHtml = elementInstance.shadowRoot
+        ? elementInstance.getInnerHTML({ includeShadowRoots: true })
+        : elementInstance.innerHTML;
+      const elementTree = parseFragment(elementHtml);
+
+      node.childNodes = node.childNodes.length === 0
+        ? elementTree.childNodes
+        : [...elementTree.childNodes, ...node.childNodes];
     }
 
     if (node.childNodes && node.childNodes.length > 0) {
-      await renderComponentRoots(node, includeShadowRoots);
+      await renderComponentRoots(node);
     }
 
     // does this only apply to `<template>` tags?
     if (node.content && node.content.childNodes && node.content.childNodes.length > 0) {
-      await renderComponentRoots(node.content, includeShadowRoots);
+      await renderComponentRoots(node.content);
     }
   }
 
@@ -57,9 +60,14 @@ async function registerDependencies(moduleURL) {
     sourceType: 'module'
   }), {
     async ImportDeclaration(node) {
-      const dependencyModuleURL = new URL(node.source.value, moduleURL);
+      const specifier = node.source.value;
+      const isBareSpecifier = specifier.indexOf('.') !== 0 && specifier.indexOf('/') !== 0;
+
+      if (!isBareSpecifier) {
+        const dependencyModuleURL = new URL(node.source.value, moduleURL);
 
-      await registerDependencies(dependencyModuleURL);
+        await registerDependencies(dependencyModuleURL);
+      }
     },
     async ExpressionStatement(node) {
       if (isCustomElementDefinitionNode(node)) {
@@ -117,21 +125,21 @@ async function initializeCustomElement(elementURL, tagName, attrs = []) {
   return elementInstance;
 }
 
-async function renderToString(elementURL, options = {}) {
+async function renderToString(elementURL) {
   definitions = [];
 
-  const { lightMode = false } = options;
-  const includeShadowRoots = !lightMode;
   const elementTagName = await getTagName(elementURL);
   const elementInstance = await initializeCustomElement(elementURL);
 
-  const elementHtml = elementInstance.getInnerHTML({ includeShadowRoots });
+  const elementHtml = elementInstance.shadowRoot
+    ? elementInstance.getInnerHTML({ includeShadowRoots: true })
+    : elementInstance.innerHTML;
   const elementTree = getParse(elementHtml)(elementHtml);
-  const finalTree = await renderComponentRoots(elementTree, includeShadowRoots);
-  const html = !lightMode && elementTagName ? `
+  const finalTree = await renderComponentRoots(elementTree);
+  const html = elementTagName ? `
       <${elementTagName}>
         ${serialize(finalTree)}
-      </${elementTagName}
+      </${elementTagName}>
     `
     : serialize(finalTree);
 
@@ -141,18 +149,15 @@ async function renderToString(elementURL, options = {}) {
   };
 }
 
-async function renderFromHTML(html, elements = [], options = {}) {
+async function renderFromHTML(html, elements = []) {
   definitions = [];
 
-  const { lightMode = false } = options;
-  const includeShadowRoots = !lightMode;
-
   for (const url of elements) {
     await initializeCustomElement(url);
   }
 
   const elementTree = getParse(html)(html);
-  const finalTree = await renderComponentRoots(elementTree, includeShadowRoots);
+  const finalTree = await renderComponentRoots(elementTree);
 
   return {
     html: serialize(finalTree),