@dom-expressions/jsx-compiler 0.50.0-next.15

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018-2019 Ryan Carniato
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# @dom-expressions/jsx-compiler
+
+Experimental AST-native JSX to DOM Expressions compiler implemented with Oxc.
+
+## Installation
+
+```bash
+npm install @dom-expressions/jsx-compiler
+```
+
+The package ships prebuilt native binaries as per-platform packages
+(`@dom-expressions/jsx-compiler-darwin-arm64`, `-darwin-x64`, `-linux-x64-gnu`,
+`-linux-arm64-gnu`, `-win32-x64-msvc`). Your package manager installs the one
+matching your platform automatically through `optionalDependencies`. On other
+platforms, build from source with `pnpm run build` inside
+`packages/jsx-compiler` (requires a Rust toolchain).
+
+## Usage
+
+This package exposes a compiler backend API. It is not a Vite, Rollup, or Babel
+plugin by itself; integrations should call `transform()` once per source module.
+
+```js
+const { transform } = require("@dom-expressions/jsx-compiler");
+
+const result = transform(`const view = <div>Hello</div>;`, {
+  filename: "App.jsx",
+  moduleName: "dom",
+  generate: "dom"
+});
+
+console.log(result.code);
+```
+
+`transformAsync()` is also available for integration points that expect a
+promise-returning transform:
+
+```js
+const { transformAsync } = require("@dom-expressions/jsx-compiler");
+
+const result = await transformAsync(source, {
+  filename: "App.jsx",
+  moduleName: "dom",
+  generate: "dom"
+});
+```
+
+### Solid-Style DOM
+
+Solid's DOM compiler preset uses DOM output with custom-element context
+capture enabled. This compiler defaults `contextToCustomElements` to `true` to
+match that behavior.
+
+```js
+const result = transform(source, {
+  filename: "App.jsx",
+  moduleName: "dom",
+  generate: "dom",
+  hydratable: true,
+  builtIns: ["For", "Show"]
+});
+```
+
+Use `dev: true` with `hydratable: true` to emit dev hydration walk validation
+helpers such as `getFirstChild` / `getNextSibling`.
+
+### SSR
+
+```js
+const result = transform(source, {
+  filename: "entry-server.jsx",
+  moduleName: "dom/server",
+  generate: "ssr",
+  hydratable: true,
+  builtIns: ["For", "Show"]
+});
+```
+
+### Universal
+
+```js
+const result = transform(source, {
+  filename: "scene.jsx",
+  moduleName: "renderer",
+  generate: "universal"
+});
+```
+
+### Dynamic Renderers
+
+Dynamic mode uses the universal renderer as the fallback and can route a
+configured set of native tags to the DOM renderer.
+
+```js
+const result = transform(source, {
+  filename: "hybrid.jsx",
+  moduleName: "renderer",
+  generate: "dynamic",
+  renderers: [
+    {
+      name: "dom",
+      moduleName: "dom",
+      elements: ["div", "span", "button", "input"]
+    }
+  ]
+});
+```
+
+### Source Maps
+
+Pass `sourceMap: true` to receive a JSON source map string in `result.map`.
+
+```js
+const result = transform(source, {
+  filename: "App.jsx",
+  moduleName: "dom",
+  sourceMap: true
+});
+
+console.log(result.map);
+```
+
+### Options
+
+Supported options track the Babel plugin where currently implemented:
+
+- `filename`
+- `moduleName`
+- `generate`: `"dom"`, `"ssr"`, `"universal"`, or `"dynamic"`
+- `hydratable`
+- `dev`
+- `sourceMap`
+- `contextToCustomElements`
+- `delegateEvents`
+- `delegatedEvents`
+- `omitQuotes`
+- `omitAttributeSpacing`
+- `inlineStyles`
+- `effectWrapper`: `"effect"` or `false`
+- paired wrapperless mode: `wrapConditionals: false` with `memoWrapper: false`
+- `staticMarker`
+- `validate`
+- `omitNestedClosingTags`
+- `omitLastClosingTag`
+- `builtIns`
+- `requireImportSource`
+- `renderers`
+
+## Current Scope
+
+This package is the AST-native compiler backend. It currently has checked fixture coverage for
+the DOM, hydratable DOM, dev hydratable DOM, SSR, hydratable SSR, universal, dynamic, no-inline-styles, and wrapperless renderer paths.
+
+- `generate: "dom"`
+- `generate: "ssr"`
+- `generate: "universal"`
+- `generate: "dynamic"`
+- native elements, components, fragments, refs, spreads, dynamic text, events, and
+  attribute handling covered by the checked fixture suites for those targets
+- Solid-compatible defaults such as `contextToCustomElements: true`
+- option coverage for `hydratable`, `dev`, `delegateEvents`, `delegatedEvents`,
+  `omitQuotes`, `omitAttributeSpacing`, `inlineStyles`, `effectWrapper: false`,
+  paired `wrapConditionals: false` / `memoWrapper: false`, `requireImportSource`,
+  `staticMarker`, `validate`, `omitNestedClosingTags`, `omitLastClosingTag`,
+  `builtIns`, and dynamic `renderers`
+- source maps for the implemented path
+
+## Not Implemented Yet
+
+The compiler intentionally rejects unsupported features instead of pretending to support them:
+
+- DOM `namespaceElements` sections that the current Oxc parser rejects before transform
+  (for example, hyphenated JSX member segments)
+- arbitrary custom renderer names beyond dynamic DOM renderer override plus universal fallback
+- custom `effectWrapper` / `memoWrapper` helper names
+- unpaired `wrapConditionals: false` or `memoWrapper: false`
+- unknown/custom namespaced DOM attributes outside known runtime namespaces such as `xlink`
+
+## Architecture
+
+The implementation is AST-native:
+
+1. Parse with Oxc.
+2. Transform JSX nodes with `VisitMut`.
+3. Build replacement expressions and helper declarations with `AstBuilder`.
+4. Codegen once with Oxc.
+
+The module layout mirrors the Babel plugin shape where possible:
+
+- `src/config.rs`
+- `src/shared/ast.rs`
+- `src/shared/transform.rs` for shared traversal and target dispatch
+- `src/shared/component.rs`
+- `src/shared/utils.rs`
+- `src/dom/element.rs`
+- `src/dom/template.rs`
+- `src/ssr/mod.rs`
+- `src/ssr/transform.rs`
+- `src/universal/mod.rs`
+- `src/universal/transform.rs`
+

package/index.js

@@ -0,0 +1,226 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const native = requireNative();
+
+function transform(code, options) {
+  if (typeof code !== "string") {
+    throw new TypeError(
+      "@dom-expressions/jsx-compiler transform() expects source code as a string"
+    );
+  }
+
+  const nativeOptions = validateOptions(code, options);
+  if (nativeOptions?.skip) {
+    return {
+      code,
+      map: null
+    };
+  }
+  const result = native.transform(code, nativeOptions);
+  return {
+    code: result.code,
+    map: result.map ?? null
+  };
+}
+
+function transformAsync(code, options) {
+  return Promise.resolve().then(() => transform(code, options));
+}
+
+const nativeOptionKeys = new Set([
+  "filename",
+  "moduleName",
+  "generate",
+  "hydratable",
+  "dev",
+  "sourceMap",
+  "contextToCustomElements",
+  "delegateEvents",
+  "delegatedEvents",
+  "omitQuotes",
+  "omitAttributeSpacing",
+  "inlineStyles",
+  "effectWrapper",
+  "wrapConditionals",
+  "memoWrapper",
+  "staticMarker",
+  "omitNestedClosingTags",
+  "omitLastClosingTag",
+  "builtIns",
+  "renderers"
+]);
+
+const compatibleBabelDefaults = new Map([]);
+
+function validateOptions(code, options) {
+  if (options == null) return options;
+  if (typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError(
+      "@dom-expressions/jsx-compiler transform() expects options to be an object"
+    );
+  }
+
+  const wrapperless = options.wrapConditionals === false || options.memoWrapper === false;
+  if (wrapperless) {
+    if (options.wrapConditionals !== false || options.memoWrapper !== false) {
+      throw new Error(
+        "@dom-expressions/jsx-compiler only supports wrapperless mode when `wrapConditionals: false` and `memoWrapper: false` are used together"
+      );
+    }
+  }
+
+  const nativeOptions = {};
+  for (const [key, value] of Object.entries(options)) {
+    if (key === "requireImportSource") {
+      if (value === false) continue;
+      if (typeof value !== "string") {
+        throw new TypeError(
+          "@dom-expressions/jsx-compiler `requireImportSource` option must be false or a string"
+        );
+      }
+      if (!hasJsxImportSource(code, value)) {
+        return { skip: true };
+      }
+      continue;
+    }
+    if (key === "effectWrapper") {
+      if (value === "effect") continue;
+      if (value === false) {
+        nativeOptions.effectWrapper = false;
+        continue;
+      }
+      throw new Error(
+        '@dom-expressions/jsx-compiler only supports `effectWrapper: false` or the default `"effect"`'
+      );
+    }
+    if (key === "wrapConditionals") {
+      if (value === true) continue;
+      if (value === false) {
+        nativeOptions.wrapConditionals = false;
+        continue;
+      }
+      throw new TypeError(
+        "@dom-expressions/jsx-compiler `wrapConditionals` option must be boolean"
+      );
+    }
+    if (key === "memoWrapper") {
+      if (value === "memo") continue;
+      if (value === false) {
+        nativeOptions.memoWrapper = false;
+        continue;
+      }
+      throw new Error(
+        '@dom-expressions/jsx-compiler only supports `memoWrapper: false` or the default `"memo"`'
+      );
+    }
+    if (key === "validate") {
+      if (typeof value !== "boolean") {
+        throw new TypeError("@dom-expressions/jsx-compiler `validate` option must be boolean");
+      }
+      continue;
+    }
+    if (nativeOptionKeys.has(key)) {
+      if (key === "renderers") validateRenderers(value);
+      nativeOptions[key] = value;
+      continue;
+    }
+    if (compatibleBabelDefaults.has(key)) {
+      const defaultValue = compatibleBabelDefaults.get(key);
+      if (sameOptionValue(value, defaultValue)) continue;
+      throw new Error(
+        `@dom-expressions/jsx-compiler does not support non-default \`${key}\` options yet`
+      );
+    }
+    throw new Error(`@dom-expressions/jsx-compiler received unknown option \`${key}\``);
+  }
+  return nativeOptions;
+}
+
+function hasJsxImportSource(code, source) {
+  const pattern = /@jsxImportSource\s+([^\s*]+)/g;
+  let match;
+  while ((match = pattern.exec(code))) {
+    if (match[1] === source) return true;
+  }
+  return false;
+}
+
+function validateRenderers(renderers) {
+  if (renderers == null) return;
+  if (!Array.isArray(renderers)) {
+    throw new TypeError("@dom-expressions/jsx-compiler `renderers` option must be an array");
+  }
+
+  for (const renderer of renderers) {
+    if (typeof renderer !== "object" || renderer == null || Array.isArray(renderer)) {
+      throw new TypeError("@dom-expressions/jsx-compiler renderer entries must be objects");
+    }
+    for (const key of Object.keys(renderer)) {
+      if (key !== "name" && key !== "moduleName" && key !== "elements") {
+        throw new Error(
+          `@dom-expressions/jsx-compiler received unknown renderer option \`${key}\``
+        );
+      }
+    }
+    if (renderer.name !== "dom") {
+      throw new Error(
+        "@dom-expressions/jsx-compiler dynamic renderers only support the `dom` renderer override"
+      );
+    }
+  }
+}
+
+function sameOptionValue(value, defaultValue) {
+  if (Array.isArray(defaultValue)) {
+    return Array.isArray(value) && value.length === defaultValue.length;
+  }
+  return value === defaultValue;
+}
+
+function platformArchSuffix() {
+  const { platform, arch } = process;
+  if (platform === "darwin" && (arch === "x64" || arch === "arm64")) return `darwin-${arch}`;
+  if (platform === "linux" && (arch === "x64" || arch === "arm64")) return `linux-${arch}-gnu`;
+  if (platform === "win32" && arch === "x64") return "win32-x64-msvc";
+  return null;
+}
+
+function requireNative() {
+  const explicit = process.env.JSX_DOM_EXPRESSIONS_COMPILER_NATIVE;
+  if (explicit) return require(explicit);
+
+  const suffix = platformArchSuffix();
+
+  // Local builds (napi build output) take precedence for development.
+  const localCandidates = [];
+  if (suffix) localCandidates.push(`jsx-compiler.${suffix}.node`);
+  localCandidates.push("jsx-compiler.node");
+  for (const file of localCandidates) {
+    const full = path.join(__dirname, file);
+    if (fs.existsSync(full)) return require(full);
+  }
+
+  if (suffix) {
+    try {
+      return require(`@dom-expressions/jsx-compiler-${suffix}`);
+    } catch (error) {
+      if (error.code !== "MODULE_NOT_FOUND") throw error;
+    }
+  }
+
+  throw new Error(
+    `Could not find the native @dom-expressions/jsx-compiler binary for ${process.platform}-${process.arch}` +
+      (suffix
+        ? ` (expected the @dom-expressions/jsx-compiler-${suffix} package or a local build)`
+        : " (no prebuilt binary is published for this platform)") +
+      ". Run `pnpm run build` in packages/jsx-compiler to build from source."
+  );
+}
+
+module.exports = {
+  transform,
+  transformAsync
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@dom-expressions/jsx-compiler",
+  "description": "A JSX to DOM Expressions compiler implemented with Oxc",
+  "version": "0.50.0-next.15",
+  "author": "Ryan Carniato",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ryansolid/dom-expressions.git",
+    "directory": "packages/jsx-compiler"
+  },
+  "main": "index.js",
+  "types": "types.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./types.d.ts",
+      "require": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "types.d.ts",
+    "README.md"
+  ],
+  "napi": {
+    "binaryName": "jsx-compiler",
+    "targets": [
+      "x86_64-apple-darwin",
+      "aarch64-apple-darwin",
+      "x86_64-unknown-linux-gnu",
+      "aarch64-unknown-linux-gnu",
+      "x86_64-pc-windows-msvc"
+    ]
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^3.6.2"
+  },
+  "optionalDependencies": {
+    "@dom-expressions/jsx-compiler-darwin-x64": "0.50.0-next.15",
+    "@dom-expressions/jsx-compiler-darwin-arm64": "0.50.0-next.15",
+    "@dom-expressions/jsx-compiler-linux-x64-gnu": "0.50.0-next.15",
+    "@dom-expressions/jsx-compiler-linux-arm64-gnu": "0.50.0-next.15",
+    "@dom-expressions/jsx-compiler-win32-x64-msvc": "0.50.0-next.15"
+  },
+  "scripts": {
+    "build": "napi build --release --strip --manifest-path ./Cargo.toml",
+    "build:debug": "napi build --manifest-path ./Cargo.toml",
+    "lint": "cargo clippy --manifest-path ./Cargo.toml -- -D warnings",
+    "test": "pnpm run build:debug && jest --no-cache",
+    "artifacts": "napi artifacts",
+    "napi:version": "napi version && node ./sync-optional-deps.mjs",
+    "create-npm-dirs": "napi create-npm-dirs"
+  }
+}

package/types.d.ts

@@ -0,0 +1,41 @@
+export interface TransformOptions {
+  filename?: string;
+  moduleName?: string;
+  generate?: "dom" | "ssr" | "universal" | "dynamic";
+  hydratable?: boolean;
+  dev?: boolean;
+  sourceMap?: boolean;
+  contextToCustomElements?: boolean;
+  delegateEvents?: boolean;
+  delegatedEvents?: string[];
+  omitQuotes?: boolean;
+  omitAttributeSpacing?: boolean;
+  inlineStyles?: boolean;
+  effectWrapper?: "effect" | false;
+  wrapConditionals?: boolean;
+  memoWrapper?: "memo" | false;
+  staticMarker?: string;
+  validate?: boolean;
+  omitNestedClosingTags?: boolean;
+  omitLastClosingTag?: boolean;
+  builtIns?: string[];
+  requireImportSource?: false | string;
+  renderers?: RendererOption[];
+}
+
+export interface RendererOption {
+  name: string;
+  moduleName?: string;
+  elements: string[];
+}
+
+export interface TransformResult {
+  code: string;
+  map?: string | null;
+}
+
+export function transform(code: string, options?: TransformOptions | null): TransformResult;
+export function transformAsync(
+  code: string,
+  options?: TransformOptions | null
+): Promise<TransformResult>;