vite-plugin-xhtml2shadow 0.0.1

package/README.md

@@ -0,0 +1,119 @@
+# vite-plugin-xhtml2shadow
+
+A vite plugin that parses XHTML files into JavaScript functions
+that produce a shadow root with that HTML.
+
+## Installation
+
+You should install this plugin as a dev tool. To use the plugin, you
+must also install the `dubc-client-global-css` package as a non-dev
+dependecy:
+
+```bash
+npm i -D vite-plugin-xhtml2shadow
+npm i dubc-client-global-css
+```
+
+## Example usage
+
+You can now create web components that reference markup instead of
+using cumbersome JavaScript APIs:
+
+**login-form.xhtml**:
+```xhtml
+<form>
+  <label>
+    Email
+    <input name="email" type="email" placeholder="Email"/>
+  </label>
+  <label>
+    Password
+    <input name="password" type="password" placeholder="Password"/>
+  </label>
+  <button type="submit">Submit</button>
+</form>
+<style>
+form {
+  display: flex;
+  flex-flow: column nowrap;
+}
+/* ...and so on */
+</style>
+```
+
+**login-form.ts**:
+```TypeScript
+import build from "./login-form.xhtml"
+
+class LoginForm extends HTMLElement {
+
+  constructor() {
+    super()
+    build(this)
+    const submit = this.shadowRoot!.querySelector("button")!
+    submit.onclick = () => {
+      // perform login here
+    }
+  }
+
+}
+customElements.define("login-form", LoginForm)
+```
+
+## Stylesheets
+
+Style elements are not added directly to the shadow root's HTML.
+Instead, the style rules are added to a `CSSStyleSheet` singleton,
+which the shadow root then adopts. This prevents the creation of
+multiple duplicate style sheets if the component is created many times.
+
+Additionally, you can set a global style sheet via the
+`dubc-client-global-css` package's `setCSS` method:
+
+```TypeScript
+import { setCSS } from "dubc-client-global-css"
+import css from "/src/global.css?raw"
+
+const globalCSS = new CSSStyleSheet()
+globalCSS.replaceSync(css)
+setCSS(globalCSS)
+```
+
+Every shadow root created by this plugin will then adopt the global
+style sheet, allowing you to re-use design across your entire app.
+
+## XHTML notes
+
+Why does this plugin use `.xhtml` files and not `.html` files? There
+are two reasons.
+
+First, `vite` already gives special handling to `.html` files, so
+this plugin doesn't interfere with that.
+
+Second, HTML5 doesn't allow self-closing tags for custom elements,
+but XHTML does. If you're used to using frameworks like React,
+you know that self-closing tags that represent self-contained components
+make the markup much easier to read.
+
+Since XHTML is XML, and XML doesn't support a lot of named entities,
+you'll need to escape their unicode values instead. In practice this
+issue only comes up with non-breaking spaces. Instead of using `&nbsp;`
+like you would in HTML, use `&#x00A0;` instead.
+
+Note that although you _authoring_ your markup as XHTML, the plugin
+produces JavaScript that creates HTML5 elements.
+
+## Server-Side Rendering
+
+If the passed-in element already has a shadow root, the functions
+produced by this plugin do nothing, just silently return. This is
+done to support web components that were rendered by a server via Declarative Shadow DOM.
+
+## Viteness
+
+This plugin is vite-specific because it relies on vite's ability to
+import static assets as URLs. This is done for `href` and `src`
+attributes that reference a relative URL or an absolute URL that
+begins with `/`. Doing so allows you to specify an asset in your
+`/src` directory via its path, but the plugin will output the correct
+hashed URL when building with vite.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { type PluginOption } from "vite";
+export default function xhtml2shadow(): PluginOption;

package/dist/index.js

@@ -0,0 +1,132 @@
+import { JSDOM } from "jsdom";
+import CleanCSS from "clean-css";
+export default function xhtml2shadow() {
+    return {
+        name: "xhtml2shadow",
+        transform: {
+            filter: {
+                id: /\.(xhtml)$/,
+            },
+            handler(src) {
+                return {
+                    code: compile(src),
+                    map: null,
+                };
+            },
+        },
+    };
+}
+function compile(src) {
+    const parser = new Parser(src);
+    parser.go();
+    let code = `import {getCSS} from "dubc-client-global-css";`;
+    code += parser.style.s;
+    code += parser.code.s;
+    code += "}";
+    return code;
+}
+class Parser {
+    jsdom;
+    code = new SB("v");
+    style = new SB("s");
+    parsed;
+    constructor(src) {
+        src = "<div>" + src + "</div>";
+        this.jsdom = new JSDOM();
+        const parser = new this.jsdom.window.DOMParser();
+        const parsed = parser.parseFromString(src, "application/xhtml+xml");
+        const n = parsed.querySelector("parsererror");
+        if (n !== null) {
+            throw new Error(n.textContent);
+        }
+        this.code.write(`export default function xhtml(el){`);
+        this.code.write(`if(el.shadowRoot!==null)return;`);
+        this.code.write(`const sh=el.attachShadow({mode:"open",delegatesFocus:true});`); // TODO, more options
+        this.code.write(`sh.adoptedStyleSheets.push(getCSS());`);
+        this.parsed = parsed;
+    }
+    go() {
+        for (const x of this.parsed.documentElement.childNodes) {
+            const v = this.#node(x);
+            if (v !== undefined)
+                this.code.write(`sh.append(${v});`);
+        }
+    }
+    #nodeId(node) {
+        if (node instanceof this.jsdom.window.Comment)
+            return;
+        if (node instanceof this.jsdom.window.Text)
+            return this.#text(node);
+        if (node instanceof this.jsdom.window.Element)
+            return this.#element(node);
+    }
+    #node(node) {
+        const id = this.#nodeId(node);
+        if (id === undefined)
+            return;
+        for (const x of node.childNodes) {
+            const childId = this.#node(x);
+            if (childId !== undefined)
+                this.code.write(`${id}.append(${childId});`);
+        }
+        return id;
+    }
+    #text(text) {
+        const s = text.textContent;
+        if (s === null)
+            return;
+        if (s.trim() === "")
+            return;
+        const v = this.code.next();
+        this.code.write(`const ${v} = document.createTextNode(${esc(s)});`);
+        return v;
+    }
+    #element(el) {
+        if (el.tagName === "style")
+            return this.#style(el);
+        const tag = el.tagName.toLowerCase();
+        const v = this.code.next();
+        this.code.write(`const ${v}=document.createElement(${esc(tag)});`);
+        for (const x of el.attributes) {
+            let { name, value } = x;
+            if (name === "src" || name === "href") {
+                if (value.startsWith(".") || value.startsWith("/")) {
+                    const imp = this.style.next();
+                    this.style.write(`import ${imp} from ${esc(value)};`);
+                    value = imp;
+                }
+            }
+            else {
+                value = esc(value);
+            }
+            this.code.write(`${v}.setAttribute(${esc(name)}, ${value});`);
+        }
+        return v;
+    }
+    #style(el) {
+        const v = this.style.next();
+        const css = new CleanCSS().minify(el.textContent ?? "");
+        this.style.write(`const ${v}=new CSSStyleSheet();`);
+        this.style.write(`${v}.replaceSync(${esc(css.styles)});`);
+        this.code.write(`sh.adoptedStyleSheets.push(${v});`);
+    }
+}
+class SB {
+    prefix;
+    s = "";
+    #id = 0;
+    next() {
+        this.#id++;
+        return this.prefix + this.#id;
+    }
+    constructor(prefix) {
+        this.prefix = prefix;
+    }
+    write(s) {
+        this.s += s;
+    }
+}
+function esc(s) {
+    return JSON.stringify(s);
+}
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "vite-plugin-xhtml2shadow",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "Converts .xhtml files into JavaScript code that produces a shadow root with that HTML.",
+  "keywords": ["vite-plugin"],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "README.md",
+    "dist/index.js",
+    "dist/index.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "test": "vitest --coverage"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/p-jack/dubc.git"
+  },
+  "author": "Paul Jack",
+  "license": "BSD-3-Clause",
+  "bugs": {
+    "url": "https://github.com/p-jack/dubc/issues"
+  },
+  "homepage": "https://github.com/p-jack/dubc#readme",
+  "devDependencies": {
+    "@types/clean-css": "^4.2.11",
+    "@types/jsdom": "^28.0.3",
+    "@vitest/coverage-v8": "^4.1.7",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  },
+  "dependencies": {
+    "clean-css": "^5.3.3",
+    "jsdom": "^29.1.1",
+    "vite": "^8"
+  }
+}