feat: add dom createElement adapter with fragment support.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/jsx",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Runtime JSX tagged template that renders DOM or React trees anywhere with or without a build step.",
   "keywords": [
     "jsx runtime",
@@ -136,6 +136,7 @@
     "test:watch": "cross-env KNIGHTED_JSX_CLI_TEST=1 vitest",
     "test:e2e": "npm run build && npm run setup:wasm && npm run build:fixture && playwright test",
     "build:fixture": "node scripts/build-rspack-fixture.mjs",
+    "demo:e2e-fixture": "npm run build && npx serve . -l tcp://127.0.0.1:4173",
     "demo:node-ssr": "node test/fixtures/node-ssr/render.mjs",
     "dev": "vite dev --config vite.config.ts",
     "build:demo": "vite build --config vite.config.ts",

playwright/esm-demo.spec.ts

@@ -6,6 +6,11 @@ const hybridSelectors = {
   litHost: 'lit-hosts-react',
   litReactBadge: 'lit-hosts-react .hybrid-react-badge',
   liteMetrics: '#lite-entrypaths .lite-metric',
+  createElementCard: '.create-element-card',
+  createElementCounter: '.create-element-value',
+  createElementNodeType: '.create-element-node-type',
+  createElementButton: '.create-element-button',
+  createElementFragmentItems: '.create-element-fragment-item',
 }
 
 const overviewSelectors = {
@@ -20,7 +25,7 @@ test.describe('esm demo via local dist fixture', () => {
   test('renders nested DOM trees and increments counter', async ({ page }) => {
     await page.goto('/test/fixtures/e2e.html')
 
-    const counterButton = page.locator('.counter-button')
+    const counterButton = page.getByRole('button', { name: 'Increment', exact: true })
     const counterLabel = page.locator('.counter-value')
 
     await expect(counterLabel).toHaveText('0')
@@ -56,4 +61,20 @@ test.describe('esm demo via local dist fixture', () => {
     ).toHaveText(/Connected|Paused/)
     await expect(page.locator(hybridSelectors.liteMetrics)).toHaveCount(4)
   })
+
+  test('renders createElement + Fragment output as real DOM nodes', async ({ page }) => {
+    await page.goto('/test/fixtures/e2e.html')
+
+    const createElementCard = page.locator(hybridSelectors.createElementCard)
+    const createElementCounter = page.locator(hybridSelectors.createElementCounter)
+    const createElementButton = page.locator(hybridSelectors.createElementButton)
+
+    await expect(createElementCard).toBeVisible()
+    await expect(page.locator(hybridSelectors.createElementNodeType)).toHaveText('1')
+    await expect(page.locator(hybridSelectors.createElementFragmentItems)).toHaveCount(2)
+
+    await expect(createElementCounter).toHaveText('0')
+    await createElementButton.click()
+    await expect(createElementCounter).toHaveText('1')
+  })
 })

src/internal/dom-create-element.ts

@@ -0,0 +1,156 @@
+import type { Namespace } from './attribute-resolution.js'
+import type { JsxComponent, JsxRenderable } from './jsx-types.js'
+
+export declare const FragmentToken: unique symbol
+export type JsxFragmentToken = typeof FragmentToken
+
+export const Fragment = Symbol.for('@knighted/jsx::Fragment') as JsxFragmentToken
+
+type JsxPropsRecord = Record<string, unknown>
+const CREATE_ELEMENT_NAMESPACE_PROP = '__jsxNs'
+
+export type JsxCreateElement = {
+  (type: JsxFragmentToken, props: null, ...children: JsxRenderable[]): DocumentFragment
+  <Props extends JsxPropsRecord>(
+    type: JsxComponent<Props>,
+    props: (Props & { children?: JsxRenderable | JsxRenderable[] }) | null,
+    ...children: JsxRenderable[]
+  ): JsxRenderable
+  (
+    type: string,
+    props: JsxPropsRecord | null,
+    ...children: JsxRenderable[]
+  ): JsxRenderable
+}
+
+type DomCreateElementHelpers = {
+  ensureDomAvailable: () => void
+  appendChildValue: (parent: Node & ParentNode, value: JsxRenderable) => void
+  setDomProp: (
+    element: Element,
+    name: string,
+    value: unknown,
+    namespace: Namespace,
+  ) => void
+  isPromiseLike: (value: unknown) => value is PromiseLike<unknown>
+}
+
+const resolveChildrenForCreateElement = (
+  props: JsxPropsRecord,
+  children: JsxRenderable[],
+) => {
+  if (children.length > 0) {
+    return children
+  }
+
+  if (!Object.prototype.hasOwnProperty.call(props, 'children')) {
+    return []
+  }
+
+  return [props.children as JsxRenderable]
+}
+
+const createPropsForComponent = (props: JsxPropsRecord, children: JsxRenderable[]) => {
+  const nextProps = { ...props }
+
+  if (children.length === 1) {
+    nextProps.children = children[0]
+  } else if (children.length > 1) {
+    nextProps.children = children
+  } else {
+    delete nextProps.children
+  }
+
+  return nextProps
+}
+
+const resolveNamespaceOverride = (props: JsxPropsRecord): Namespace | undefined => {
+  if (!Object.prototype.hasOwnProperty.call(props, CREATE_ELEMENT_NAMESPACE_PROP)) {
+    return undefined
+  }
+
+  const override = props[CREATE_ELEMENT_NAMESPACE_PROP]
+  delete props[CREATE_ELEMENT_NAMESPACE_PROP]
+
+  if (override === 'svg' || override === null) {
+    return override
+  }
+
+  throw new Error(`${CREATE_ELEMENT_NAMESPACE_PROP} must be "svg" or null when provided.`)
+}
+
+export const createDomCreateElement = ({
+  ensureDomAvailable,
+  appendChildValue,
+  setDomProp,
+  isPromiseLike,
+}: DomCreateElementHelpers): JsxCreateElement => {
+  function createElement(
+    type: JsxFragmentToken,
+    props: null,
+    ...children: JsxRenderable[]
+  ): DocumentFragment
+  function createElement<Props extends JsxPropsRecord>(
+    type: JsxComponent<Props>,
+    props: (Props & { children?: JsxRenderable | JsxRenderable[] }) | null,
+    ...children: JsxRenderable[]
+  ): JsxRenderable
+  function createElement(
+    type: string,
+    props: JsxPropsRecord | null,
+    ...children: JsxRenderable[]
+  ): JsxRenderable
+  function createElement(
+    type: string | JsxComponent | JsxFragmentToken,
+    props: JsxPropsRecord | null,
+    ...children: JsxRenderable[]
+  ): JsxRenderable {
+    ensureDomAvailable()
+
+    const nextProps = props ? { ...props } : {}
+    const resolvedChildren = resolveChildrenForCreateElement(nextProps, children)
+
+    if (type === Fragment) {
+      const fragment = document.createDocumentFragment()
+      resolvedChildren.forEach(child => appendChildValue(fragment, child))
+      return fragment
+    }
+
+    if (typeof type === 'function') {
+      const result = type(createPropsForComponent(nextProps, resolvedChildren))
+
+      if (isPromiseLike(result)) {
+        throw new Error('Async jsx components are not supported.')
+      }
+
+      return result
+    }
+
+    if (typeof type !== 'string') {
+      throw new Error(`Unsupported jsx createElement type: ${String(type)}`)
+    }
+
+    delete nextProps.children
+    const namespaceOverride = resolveNamespaceOverride(nextProps)
+
+    const nextNamespace: Namespace = namespaceOverride ?? (type === 'svg' ? 'svg' : null)
+    const domElement =
+      nextNamespace === 'svg'
+        ? document.createElementNS('http://www.w3.org/2000/svg', type)
+        : document.createElement(type)
+
+    Object.entries(nextProps).forEach(([name, value]) => {
+      if (name === 'key') {
+        return
+      }
+
+      setDomProp(domElement, name, value, nextNamespace)
+    })
+
+    resolvedChildren.forEach(value => appendChildValue(domElement, value))
+
+    return domElement
+  }
+
+  return createElement
+}

src/internal/jsx-types.ts

@@ -0,0 +1,15 @@
+export type JsxRenderable =
+  | Node
+  | DocumentFragment
+  | string
+  | number
+  | bigint
+  | boolean
+  | null
+  | undefined
+  | Iterable<JsxRenderable>
+
+export type JsxComponent<Props = Record<string, unknown>> = {
+  (props: Props & { children?: JsxRenderable | JsxRenderable[] }): JsxRenderable
+  displayName?: string
+}

src/jsx.ts

@@ -32,25 +32,17 @@ import {
   parseEventPropName,
   resolveEventHandlerValue,
 } from './internal/event-bindings.js'
+import {
+  Fragment,
+  createDomCreateElement,
+  type JsxFragmentToken,
+  type JsxCreateElement,
+} from './internal/dom-create-element.js'
+import type { JsxComponent, JsxRenderable } from './internal/jsx-types.js'
 
 type JsxContext = TemplateContext<JsxComponent>
 type ElementWithIndex = Element & Record<string, unknown>
-
-export type JsxRenderable =
-  | Node
-  | DocumentFragment
-  | string
-  | number
-  | bigint
-  | boolean
-  | null
-  | undefined
-  | Iterable<JsxRenderable>
-
-export type JsxComponent<Props = Record<string, unknown>> = {
-  (props: Props & { children?: JsxRenderable | JsxRenderable[] }): JsxRenderable
-  displayName?: string
-}
+export type { JsxRenderable, JsxComponent } from './internal/jsx-types.js'
 
 const ensureDomAvailable = () => {
   if (typeof document === 'undefined' || typeof document.createElement !== 'function') {
@@ -477,10 +469,20 @@ const evaluateJsxNode = (
   return evaluateJsxElement(node, ctx, namespace)
 }
 
-export const jsx = (
-  templates: TemplateStringsArray,
-  ...values: unknown[]
-): JsxRenderable => {
+export const createElement: JsxCreateElement = createDomCreateElement({
+  ensureDomAvailable,
+  appendChildValue,
+  setDomProp,
+  isPromiseLike,
+})
+
+type JsxTaggedTemplate = {
+  (templates: TemplateStringsArray, ...values: unknown[]): JsxRenderable
+  createElement: typeof createElement
+  Fragment: JsxFragmentToken
+}
+
+const jsxTag = (templates: TemplateStringsArray, ...values: unknown[]): JsxRenderable => {
   ensureDomAvailable()
   const build = buildTemplate<JsxComponent>(templates, values)
   const result = parseSync('inline.jsx', build.source, parserOptions)
@@ -505,3 +507,8 @@ export const jsx = (
 
   return evaluateJsxNode(root, ctx, null)
 }
+
+export const jsx = Object.assign(jsxTag, {
+  createElement,
+  Fragment,
+}) as JsxTaggedTemplate

test/fixtures/e2e.html

@@ -768,6 +768,67 @@ <h2>Stateful counter rendered with <code>jsx</code></h2>
           </section>
         `
       }
+      const CreateElementCounter = ({ start = 0 }) => {
+        let value = start
+        const valueLabel = jsx.createElement(
+          'strong',
+          { class: 'create-element-value' },
+          String(value),
+        )
+        const nodeTypeLabel = jsx.createElement(
+          'code',
+          { class: 'create-element-node-type' },
+          String(valueLabel.nodeType),
+        )
+        const increment = () => {
+          value += 1
+          valueLabel.textContent = String(value)
+        }
+
+        return jsx.createElement(
+          'section',
+          { class: 'card dom-card create-element-card' },
+          jsx.createElement(
+            'header',
+            null,
+            jsx.createElement('p', { class: 'eyebrow' }, 'createElement facade'),
+            jsx.createElement('h2', null, 'DOM parity with jsx.createElement + Fragment'),
+          ),
+          jsx.createElement(
+            'p',
+            null,
+            'This section is rendered without template literals to validate direct createElement usage.',
+          ),
+          jsx.createElement('p', null, 'Current total: ', valueLabel),
+          jsx.createElement('p', null, 'valueLabel.nodeType = ', nodeTypeLabel),
+          jsx.createElement(
+            'ul',
+            { class: 'list create-element-fragment-list' },
+            jsx.createElement(
+              jsx.Fragment,
+              null,
+              jsx.createElement(
+                'li',
+                { class: 'create-element-fragment-item' },
+                'Fragment child one',
+              ),
+              jsx.createElement(
+                'li',
+                { class: 'create-element-fragment-item' },
+                'Fragment child two',
+              ),
+            ),
+          ),
+          jsx.createElement(
+            'button',
+            {
+              class: 'counter-button create-element-button',
+              onClick: increment,
+            },
+            'Increment via createElement',
+          ),
+        )
+      }
       const reactMetrics = ['Hooks ready', 'Fragments inline', 'Suspense friendly']
       const ReactBadge = ({ label }) =>
         reactJsx`
@@ -1143,6 +1204,7 @@ <h2>All the ways to use @knighted/jsx</h2>
             </p>
           </section>
           <${Counter} start={${0}} />
+          <${CreateElementCounter} start={${0}} />
           <section class="card react-card">
             <header>
               <h2>Try the React runtime</h2>