fix: node tla, suffix handling. (#49)

Author: knightedcodemonkey

docs/runtime-helpers-overview.md

@@ -2,6 +2,9 @@
 
 This note explains how the runtime helpers behave when you call them directly—without involving the loader. Both helpers are plain JavaScript tagged template literals that lean on the `oxc-parser` WebAssembly build to interpret JSX syntax at execution time.
 
+> [!IMPORTANT]  
+> Runtime `jsx` calls must include literal JSX braces around attribute/child expressions (for example, `onClick={${handler}}`). Only the loader and TypeScript plugin auto-insert those braces; direct helper usage feeds the template straight into the parser and will throw if braces are missing.
+
 ## What happens when you call the helpers?
 
 1. **Template literal evaluation** – JavaScript collects the raw string segments (`strings`) and evaluated expressions (`values`) for the tagged template.
@@ -17,6 +20,9 @@ This note explains how the runtime helpers behave when you call them directly—
 - Works in browsers out of the box. In Node you can import `@knighted/jsx/node` to bootstrap a DOM shim (tries `linkedom`, then `jsdom`).
 - Expressions inside the template (props, children, dynamic tags) are evaluated before parsing—no special placeholder syntax is required.
 
+> [!IMPORTANT]  
+> The runtime parser only understands literal JSX syntax, so attribute expressions must include braces in the template source (e.g. `onClick={${handler}}`). The loader/plugin pipeline can insert those braces for you, but direct calls to ` jsx`` ` must already contain them.
+
 Example:
 
 ```ts

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/jsx",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "Runtime JSX tagged template that renders DOM or React trees anywhere without a build step.",
   "keywords": [
     "jsx runtime",
@@ -162,7 +162,7 @@
   "optionalDependencies": {
     "@oxc-parser/binding-darwin-arm64": "^0.105.0",
     "@oxc-parser/binding-linux-x64-gnu": "^0.105.0",
-    "@oxc-parser/binding-wasm32-wasi": "0.105.0"
+    "@oxc-parser/binding-wasm32-wasi": "^0.105.0"
   },
   "overrides": {
     "module-lookup-amd": {

package.json

@@ -0,0 +1,83 @@
+import type {
+  Expression,
+  JSXAttribute,
+  JSXElement,
+  JSXFragment,
+  JSXSpreadAttribute,
+} from '@oxc-project/types'
+import type { TemplateComponent, TemplateContext } from '../runtime/shared.js'
+
+export type Namespace = 'svg' | null
+
+export type EvaluateExpressionWithNamespace<TComponent extends TemplateComponent> = (
+  expression: Expression | JSXElement | JSXFragment,
+  ctx: TemplateContext<TComponent>,
+  namespace: Namespace,
+) => unknown
+
+export type ResolveAttributesDependencies<TComponent extends TemplateComponent> = {
+  getIdentifierName: (name: JSXAttribute['name']) => string
+  evaluateExpressionWithNamespace: EvaluateExpressionWithNamespace<TComponent>
+}
+
+export type ResolveAttributesFn<TComponent extends TemplateComponent> = (
+  attributes: (JSXAttribute | JSXSpreadAttribute)[],
+  ctx: TemplateContext<TComponent>,
+  namespace: Namespace,
+) => Record<string, unknown>
+
+export const createResolveAttributes = <TComponent extends TemplateComponent>(
+  deps: ResolveAttributesDependencies<TComponent>,
+): ResolveAttributesFn<TComponent> => {
+  const { getIdentifierName, evaluateExpressionWithNamespace } = deps
+
+  return (attributes, ctx, namespace) => {
+    const props: Record<string, unknown> = {}
+
+    attributes.forEach(attribute => {
+      if (attribute.type === 'JSXSpreadAttribute') {
+        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)
+
+      if (!attribute.value) {
+        props[name] = true
+        return
+      }
+
+      if (attribute.value.type === 'Literal') {
+        props[name] = attribute.value.value
+        return
+      }
+
+      if (attribute.value.type === 'JSXExpressionContainer') {
+        if (attribute.value.expression.type === 'JSXEmptyExpression') {
+          return
+        }
+
+        props[name] = evaluateExpressionWithNamespace(
+          attribute.value.expression,
+          ctx,
+          namespace,
+        )
+      }
+    })
+
+    return props
+  }
+}

src/internal/attribute-resolution.ts

@@ -0,0 +1,121 @@
+const captureSuffix = 'Capture'
+
+export type ParsedEventBinding = {
+  eventName: string
+  capture: boolean
+}
+
+const stripCaptureSuffix = (rawName: string): ParsedEventBinding => {
+  if (rawName.endsWith(captureSuffix)) {
+    return { eventName: rawName.slice(0, -captureSuffix.length), capture: true }
+  }
+
+  return { eventName: rawName, capture: false }
+}
+
+export const parseEventPropName = (name: string): ParsedEventBinding | null => {
+  if (!name.startsWith('on')) {
+    return null
+  }
+
+  if (name.startsWith('on:')) {
+    const raw = name.slice(3)
+    if (!raw) {
+      return null
+    }
+    const parsed = stripCaptureSuffix(raw)
+    if (!parsed.eventName) {
+      return null
+    }
+    return parsed
+  }
+
+  const raw = name.slice(2)
+  if (!raw) {
+    return null
+  }
+
+  const parsed = stripCaptureSuffix(raw)
+  if (!parsed.eventName) {
+    return null
+  }
+
+  return {
+    eventName: parsed.eventName.toLowerCase(),
+    capture: parsed.capture,
+  }
+}
+
+const isEventListenerObject = (value: unknown): value is EventListenerObject => {
+  if (!value || typeof value !== 'object') {
+    return false
+  }
+
+  return (
+    'handleEvent' in (value as Record<string, unknown>) &&
+    typeof (value as EventListenerObject).handleEvent === 'function'
+  )
+}
+
+export type EventHandlerDescriptor = {
+  handler: EventListenerOrEventListenerObject
+  capture?: boolean
+  once?: boolean
+  passive?: boolean
+  signal?: AbortSignal | null
+  options?: AddEventListenerOptions
+}
+
+const isEventHandlerDescriptor = (value: unknown): value is EventHandlerDescriptor => {
+  if (!value || typeof value !== 'object' || !('handler' in value)) {
+    return false
+  }
+
+  const handler = (value as EventHandlerDescriptor).handler
+  if (typeof handler === 'function') {
+    return true
+  }
+
+  return isEventListenerObject(handler)
+}
+
+export type ResolvedEventHandler = {
+  listener: EventListenerOrEventListenerObject
+  options?: AddEventListenerOptions
+}
+
+export const resolveEventHandlerValue = (value: unknown): ResolvedEventHandler | null => {
+  if (typeof value === 'function' || isEventListenerObject(value)) {
+    return { listener: value as EventListenerOrEventListenerObject }
+  }
+
+  if (!isEventHandlerDescriptor(value)) {
+    return null
+  }
+
+  const descriptor = value
+  let options = descriptor.options ? { ...descriptor.options } : undefined
+
+  const assignOption = <K extends keyof AddEventListenerOptions>(
+    key: K,
+    optionValue: AddEventListenerOptions[K] | null | undefined,
+  ) => {
+    if (optionValue === undefined || optionValue === null) {
+      return
+    }
+    if (!options) {
+      options = {}
+    }
+    options[key] = optionValue
+  }
+
+  assignOption('capture', descriptor.capture)
+  assignOption('once', descriptor.once)
+  assignOption('passive', descriptor.passive)
+  assignOption('signal', descriptor.signal ?? undefined)
+
+  return {
+    listener: descriptor.handler,
+    options,
+  }
+}