@knighted/jsx 1.0.0 → 1.2.0-rc.0

package/README.md

@@ -15,13 +15,17 @@ npm install @knighted/jsx
 > [!IMPORTANT]
 > This package is ESM-only and targets browsers or ESM-aware bundlers. `require()` is not supported; use native `import`/`<script type="module">` and a DOM-like environment.
 
+> [!NOTE]
+> Planning to use the React runtime (`@knighted/jsx/react`)? Install `react@>=18` and `react-dom@>=18` alongside this package so the helper can create elements and render them through ReactDOM.
+
 The parser automatically uses native bindings when it runs in Node.js. To enable the WASM binding for browser builds you also need the `@oxc-parser/binding-wasm32-wasi` package. Because npm enforces the `cpu: ["wasm32"]` flag you must opt into the install explicitly:
 
 ```sh
 npm_config_ignore_platform=true npm install @oxc-parser/binding-wasm32-wasi
 ```
 
-> Tip: public CDNs such as `esm.sh` or `jsdelivr` already publish bundles that include the WASM binding, so you can import this package directly from those endpoints in `<script type="module">` blocks without any extra setup.
+> [!TIP]
+> Public CDNs such as `esm.sh` or `jsdelivr` already publish bundles that include the WASM binding, so you can import this package directly from those endpoints in `<script type="module">` blocks without any extra setup.
 
 ## Usage
 
@@ -40,6 +44,71 @@ const button = jsx`
 document.body.append(button)
 ```
 
+### React runtime (`reactJsx`)
+
+Need to compose React elements instead of DOM nodes? Import the dedicated helper from the `@knighted/jsx/react` subpath (React 18+ and `react-dom` are still required to mount the tree):
+
+```ts
+import { reactJsx } from '@knighted/jsx/react'
+import { createRoot } from 'react-dom/client'
+
+const view = reactJsx`
+  <section className="react-demo">
+    <h2>Hello from React</h2>
+    <button onClick={${() => console.log('clicked!')}}>Tap me</button>
+  </section>
+`
+
+createRoot(document.getElementById('root')!).render(view)
+```
+
+The React runtime shares the same template semantics as `jsx`, except it returns React elements (via `React.createElement`) so you can embed other React components with `<${MyComponent} />` and use hooks/state as usual. The helper lives in a separate subpath so DOM-only consumers never pay the React dependency cost.
+
+## Loader integration
+
+Use the published loader entry (`@knighted/jsx/loader`) when you want your bundler to rewrite tagged template literals at build time. The loader finds every ` jsx`` ` (and, by default, ` reactJsx`` ` ) invocation, rebuilds the template with real JSX semantics, and hands back transformed source that can run in any environment.
+
+```js
+// rspack.config.js / webpack.config.js
+export default {
+  module: {
+    rules: [
+      {
+        test: /\.[jt]sx?$/,
+        include: path.resolve(__dirname, 'src'),
+        use: [
+          {
+            loader: '@knighted/jsx/loader',
+            options: {
+              // Both optional: restrict or rename the tagged templates.
+              // tag: 'jsx', // single-tag option
+              // tags: ['jsx', 'reactJsx'],
+            },
+          },
+        ],
+      },
+    ],
+  },
+}
+```
+
+Pair the loader with your existing TypeScript/JSX transpiler (SWC, Babel, Rspack’s builtin loader, etc.) so regular React components and the tagged templates can live side by side. The demo fixture under `test/fixtures/rspack-app` shows a full setup that mixes Lit and React:
+
+```sh
+npm run build
+npm run setup:wasm
+npm run build:fixture
+```
+
+Then point a static server at the fixture root (which serves `index.html` and the bundled `dist/bundle.js`) to see it in a browser:
+
+```sh
+# Serve the rspack fixture from the repo root
+npx http-server test/fixtures/rspack-app -p 4173
+```
+
+Visit `http://localhost:4173` (or whichever port you pick) to interact with the Lit + React demo.
+
 ### Interpolations
 
 - All dynamic values are provided through standard template literal expressions (`${...}`). Wrap them in JSX braces to keep the syntax valid: `className={${value}}`, `{${items}}`, etc.
@@ -94,7 +163,19 @@ When you are not using a bundler, load the module directly from a CDN that under
 </script>
 ```
 
-If you are building locally with Vite/Rollup/Webpack make sure the WASM binding is installable (see the `npm_config_ignore_platform` tip above) so the bundler can resolve `@oxc-parser/binding-wasm32-wasi`.
+If you are building locally with Vite/Rollup/Webpack make sure the WASM binding is installable so the bundler can resolve `@oxc-parser/binding-wasm32-wasi` (details below).
+
+### Installing the WASM binding locally
+
+`@oxc-parser/binding-wasm32-wasi` publishes with `"cpu": ["wasm32"]`, so npm/yarn/pnpm skip it on macOS and Linux unless you override the platform guard. Run the helper script after cloning (or whenever you clean `node_modules`) to pull the binding into place for the Vite demo and any other local bundler builds:
+
+```sh
+npm run setup:wasm
+```
+
+The script downloads the published tarball via `npm pack`, extracts it into `node_modules/@oxc-parser/binding-wasm32-wasi`, and removes the temporary archive so your lockfile stays untouched. If you need to test a different binding build, set `WASM_BINDING_PACKAGE` before running the script (for example, `WASM_BINDING_PACKAGE=@oxc-parser/binding-wasm32-wasi@0.100.0 npm run setup:wasm`).
+
+Prefer the manual route? You can still run `npm_config_ignore_platform=true npm install --no-save @oxc-parser/binding-wasm32-wasi@^0.99.0`, but the script above replicates the vendored behavior with less ceremony.
 
 ### Lite bundle entry
 
@@ -118,7 +199,7 @@ Tests live in `test/jsx.test.ts` and cover DOM props/events, custom components,
 
 ## Browser demo / Vite build
 
-This repo ships with a ready-to-run Vite demo under `examples/browser` that bundles the library (and the WASM binding vendored in `vendor/binding-wasm32-wasi`). Use it for a full end-to-end verification in a real browser (the demo now imports `@knighted/jsx/lite` so you can confirm the lighter entry behaves identically):
+This repo ships with a ready-to-run Vite demo under `examples/browser` that bundles the library (make sure you have installed the WASM binding via the command above first). Use it for a full end-to-end verification in a real browser (the demo imports `@knighted/jsx/lite` so you can confirm the lighter entry behaves identically):
 
 ```sh
 # Start a dev server at http://localhost:5173
@@ -129,7 +210,7 @@ npm run build:demo
 npm run preview
 ```
 
-The Vite config aliases `@oxc-parser/binding-wasm32-wasi` to the vendored copy so you don't have to perform any extra install tricks locally, while production consumers can still rely on the published package. For a zero-build verification of the lite bundle, open `examples/esm-demo-lite.html` locally (double-click or run `open examples/esm-demo-lite.html`) or visit the deployed GitHub Pages build produced by `.github/workflows/deploy-demo.yml` (it serves that same lite HTML demo).
+For a zero-build verification of the lite bundle, open `examples/esm-demo-lite.html` locally (double-click or run `open examples/esm-demo-lite.html`) or visit the deployed GitHub Pages build produced by `.github/workflows/deploy-demo.yml` (it serves that same lite HTML demo).
 
 ## Limitations
 

package/dist/cjs/jsx.cjs

@@ -2,57 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.jsx = void 0;
 const oxc_parser_1 = require("oxc-parser");
-const OPEN_TAG_RE = /<\s*$/;
-const CLOSE_TAG_RE = /<\/\s*$/;
-const PLACEHOLDER_PREFIX = '__KX_EXPR__';
-let invocationCounter = 0;
-const parserOptions = {
-    lang: 'jsx',
-    sourceType: 'module',
-    range: true,
-    preserveParens: true,
-};
+const shared_js_1 = require("./runtime/shared.cjs");
 const ensureDomAvailable = () => {
     if (typeof document === 'undefined' || typeof document.createElement !== 'function') {
         throw new Error('The jsx template tag requires a DOM-like environment (document missing).');
     }
 };
-const formatParserError = (error) => {
-    let message = `[oxc-parser] ${error.message}`;
-    if (error.labels?.length) {
-        const label = error.labels[0];
-        if (label.message) {
-            message += `\n${label.message}`;
-        }
-    }
-    if (error.codeframe) {
-        message += `\n${error.codeframe}`;
-    }
-    return message;
-};
-const extractRootNode = (program) => {
-    for (const statement of program.body) {
-        if (statement.type === 'ExpressionStatement') {
-            const expression = statement.expression;
-            if (expression.type === 'JSXElement' || expression.type === 'JSXFragment') {
-                return expression;
-            }
-        }
-    }
-    throw new Error('The jsx template must contain a single JSX element or fragment.');
-};
-const getIdentifierName = (identifier) => {
-    switch (identifier.type) {
-        case 'JSXIdentifier':
-            return identifier.name;
-        case 'JSXNamespacedName':
-            return `${identifier.namespace.name}:${identifier.name.name}`;
-        case 'JSXMemberExpression':
-            return `${getIdentifierName(identifier.object)}.${identifier.property.name}`;
-        default:
-            return '';
-    }
-};
 const isNodeLike = (value) => {
     if (typeof Node === 'undefined') {
         return false;
@@ -71,11 +26,6 @@ const isPromiseLike = (value) => {
     }
     return typeof value.then === 'function';
 };
-const normalizeJsxText = (value) => {
-    const collapsed = value.replace(/\r/g, '').replace(/\n\s+/g, ' ');
-    const trimmed = collapsed.trim();
-    return trimmed.length > 0 ? trimmed : '';
-};
 const setDomProp = (element, name, value) => {
     if (value === false || value === null || value === undefined) {
         return;
@@ -165,17 +115,18 @@ const appendChildValue = (parent, value) => {
     }
     parent.appendChild(document.createTextNode(String(value)));
 };
-const resolveAttributes = (attributes, ctx) => {
+const evaluateExpressionWithNamespace = (expression, ctx, namespace) => (0, shared_js_1.evaluateExpression)(expression, ctx, node => evaluateJsxNode(node, ctx, namespace));
+const resolveAttributes = (attributes, ctx, namespace) => {
     const props = {};
     attributes.forEach(attribute => {
         if (attribute.type === 'JSXSpreadAttribute') {
-            const spreadValue = evaluateExpression(attribute.argument, ctx);
+            const spreadValue = evaluateExpressionWithNamespace(attribute.argument, ctx, namespace);
             if (spreadValue && typeof spreadValue === 'object' && !Array.isArray(spreadValue)) {
                 Object.assign(props, spreadValue);
             }
             return;
         }
-        const name = getIdentifierName(attribute.name);
+        const name = (0, shared_js_1.getIdentifierName)(attribute.name);
         if (!attribute.value) {
             props[name] = true;
             return;
@@ -188,13 +139,13 @@ const resolveAttributes = (attributes, ctx) => {
             if (attribute.value.expression.type === 'JSXEmptyExpression') {
                 return;
             }
-            props[name] = evaluateExpression(attribute.value.expression, ctx);
+            props[name] = evaluateExpressionWithNamespace(attribute.value.expression, ctx, namespace);
         }
     });
     return props;
 };
-const applyDomAttributes = (element, attributes, ctx) => {
-    const props = resolveAttributes(attributes, ctx);
+const applyDomAttributes = (element, attributes, ctx, namespace) => {
+    const props = resolveAttributes(attributes, ctx, namespace);
     Object.entries(props).forEach(([name, value]) => {
         if (name === 'key') {
             return;
@@ -211,7 +162,7 @@ const evaluateJsxChildren = (children, ctx, namespace) => {
     children.forEach(child => {
         switch (child.type) {
             case 'JSXText': {
-                const text = normalizeJsxText(child.value);
+                const text = (0, shared_js_1.normalizeJsxText)(child.value);
                 if (text) {
                     resolved.push(text);
                 }
@@ -221,11 +172,11 @@ const evaluateJsxChildren = (children, ctx, namespace) => {
                 if (child.expression.type === 'JSXEmptyExpression') {
                     break;
                 }
-                resolved.push(evaluateExpression(child.expression, ctx));
+                resolved.push(evaluateExpressionWithNamespace(child.expression, ctx, namespace));
                 break;
             }
             case 'JSXSpreadChild': {
-                const spreadValue = evaluateExpression(child.expression, ctx);
+                const spreadValue = evaluateExpressionWithNamespace(child.expression, ctx, namespace);
                 if (spreadValue !== undefined && spreadValue !== null) {
                     resolved.push(spreadValue);
                 }
@@ -241,7 +192,7 @@ const evaluateJsxChildren = (children, ctx, namespace) => {
     return resolved;
 };
 const evaluateComponent = (element, ctx, component, namespace) => {
-    const props = resolveAttributes(element.openingElement.attributes, ctx);
+    const props = resolveAttributes(element.openingElement.attributes, ctx, namespace);
     const childValues = evaluateJsxChildren(element.children, ctx, namespace);
     if (childValues.length === 1) {
         props.children = childValues[0];
@@ -257,7 +208,7 @@ const evaluateComponent = (element, ctx, component, namespace) => {
 };
 const evaluateJsxElement = (element, ctx, namespace) => {
     const opening = element.openingElement;
-    const tagName = getIdentifierName(opening.name);
+    const tagName = (0, shared_js_1.getIdentifierName)(opening.name);
     const component = ctx.components.get(tagName);
     if (component) {
         return evaluateComponent(element, ctx, component, namespace);
@@ -270,7 +221,7 @@ const evaluateJsxElement = (element, ctx, namespace) => {
     const domElement = nextNamespace === 'svg'
         ? document.createElementNS('http://www.w3.org/2000/svg', tagName)
         : document.createElement(tagName);
-    applyDomAttributes(domElement, opening.attributes, ctx);
+    applyDomAttributes(domElement, opening.attributes, ctx, nextNamespace);
     const childValues = evaluateJsxChildren(element.children, ctx, childNamespace);
     childValues.forEach(value => appendChildValue(domElement, value));
     return domElement;
@@ -284,119 +235,14 @@ const evaluateJsxNode = (node, ctx, namespace) => {
     }
     return evaluateJsxElement(node, ctx, namespace);
 };
-const walkAst = (node, visitor) => {
-    if (!node || typeof node !== 'object') {
-        return;
-    }
-    const candidate = node;
-    if (typeof candidate.type !== 'string') {
-        return;
-    }
-    visitor(candidate);
-    Object.values(candidate).forEach(value => {
-        if (!value) {
-            return;
-        }
-        if (Array.isArray(value)) {
-            value.forEach(child => walkAst(child, visitor));
-            return;
-        }
-        if (typeof value === 'object') {
-            walkAst(value, visitor);
-        }
-    });
-};
-const collectPlaceholderNames = (expression, ctx) => {
-    const placeholders = new Set();
-    walkAst(expression, node => {
-        if (node.type === 'Identifier' && ctx.placeholders.has(node.name)) {
-            placeholders.add(node.name);
-        }
-    });
-    return Array.from(placeholders);
-};
-const evaluateExpression = (expression, ctx) => {
-    if (expression.type === 'JSXElement' || expression.type === 'JSXFragment') {
-        return evaluateJsxNode(expression, ctx, null);
-    }
-    if (!('range' in expression) || !expression.range) {
-        throw new Error('Unable to evaluate expression: missing source range information.');
-    }
-    const [start, end] = expression.range;
-    const source = ctx.source.slice(start, end);
-    const placeholders = collectPlaceholderNames(expression, ctx);
-    try {
-        const evaluator = new Function(...placeholders, `"use strict"; return (${source});`);
-        const args = placeholders.map(name => ctx.placeholders.get(name));
-        return evaluator(...args);
-    }
-    catch (error) {
-        throw new Error(`Failed to evaluate expression ${source}: ${error.message}`);
-    }
-};
-const sanitizeIdentifier = (value) => {
-    const cleaned = value.replace(/[^a-zA-Z0-9_$]/g, '');
-    if (!cleaned) {
-        return 'Component';
-    }
-    if (!/[A-Za-z_$]/.test(cleaned[0])) {
-        return `Component${cleaned}`;
-    }
-    return cleaned;
-};
-const ensureBinding = (value, bindings, bindingLookup) => {
-    const existing = bindingLookup.get(value);
-    if (existing) {
-        return existing;
-    }
-    const descriptor = value.displayName || value.name || `Component${bindings.length}`;
-    const baseName = sanitizeIdentifier(descriptor);
-    let candidate = baseName;
-    let suffix = 1;
-    while (bindings.some(binding => binding.name === candidate)) {
-        candidate = `${baseName}${suffix++}`;
-    }
-    const binding = { name: candidate, value };
-    bindings.push(binding);
-    bindingLookup.set(value, binding);
-    return binding;
-};
-const buildTemplate = (strings, values) => {
-    const raw = strings.raw ?? strings;
-    const placeholders = new Map();
-    const bindings = [];
-    const bindingLookup = new Map();
-    let source = raw[0] ?? '';
-    const templateId = invocationCounter++;
-    let placeholderIndex = 0;
-    for (let idx = 0; idx < values.length; idx++) {
-        const chunk = raw[idx] ?? '';
-        const nextChunk = raw[idx + 1] ?? '';
-        const value = values[idx];
-        const isTagNamePosition = OPEN_TAG_RE.test(chunk) || CLOSE_TAG_RE.test(chunk);
-        if (isTagNamePosition && typeof value === 'function') {
-            const binding = ensureBinding(value, bindings, bindingLookup);
-            source += binding.name + nextChunk;
-            continue;
-        }
-        if (isTagNamePosition && typeof value === 'string') {
-            source += value + nextChunk;
-            continue;
-        }
-        const placeholder = `${PLACEHOLDER_PREFIX}${templateId}_${placeholderIndex++}__`;
-        placeholders.set(placeholder, value);
-        source += placeholder + nextChunk;
-    }
-    return { source, placeholders, bindings };
-};
 const jsx = (templates, ...values) => {
     ensureDomAvailable();
-    const build = buildTemplate(templates, values);
-    const result = (0, oxc_parser_1.parseSync)('inline.jsx', build.source, parserOptions);
+    const build = (0, shared_js_1.buildTemplate)(templates, values);
+    const result = (0, oxc_parser_1.parseSync)('inline.jsx', build.source, shared_js_1.parserOptions);
     if (result.errors.length > 0) {
-        throw new Error(formatParserError(result.errors[0]));
+        throw new Error((0, shared_js_1.formatParserError)(result.errors[0]));
     }
-    const root = extractRootNode(result.program);
+    const root = (0, shared_js_1.extractRootNode)(result.program);
     const ctx = {
         source: build.source,
         placeholders: build.placeholders,