@plastic-js/plastic 1.0.3 → 1.0.5

package/README.md

@@ -24,7 +24,7 @@ Plastic enforces a strict one-way data flow contract: data travels **downward**
 
 ### Read-Only Props Proxy
 
-When a JSX element carries any attributes or children, the Babel plugin compiles all props into a single `mergeProps(...)` call. The result is a read-only Proxy — any attempt to write a prop throws immediately:
+When a JSX element compiles to the general `jsx()` path (see [JSX Compilation Paths](#jsx-compilation-paths) — i.e. components, `<Dynamic>`, fragments, or intrinsics with a spread / non-literal attribute), the Babel plugin compiles all props into a single `mergeProps(...)` call. The result is a read-only Proxy — any attempt to write a prop throws immediately:
 
 ```js
 const Child = (props) => {
@@ -93,7 +93,7 @@ Plastic and Solid diverge significantly on how `class` / `className` is resolved
 - **Solid** has two distinct modes selected at compile time:
   - *Merging mode* (no spread present): static and dynamic class attributes are concatenated into a single space-separated string.
   - *Assignment mode* (any spread present): the compiler switches to sequential `element.className = value` assignment, so the **last** class-bearing prop or spread wins and any earlier class declarations are overwritten.
-- **Plastic** has only one mode: the Babel plugin hands every attribute — static, dynamic, and spread alike — to the runtime `mergeProps` unchanged, and `mergeProps` performs the merge. All three source types are concatenated additively, and each source's value may itself be either a string or an object (e.g. `{ foo: true, bar: isActive() }`); both forms are normalized and merged into the final class list.
+- **Plastic** has only one mode. Whenever an element compiles to the `jsx()` path (which any spread forces it into — see [JSX Compilation Paths](#jsx-compilation-paths)), the Babel plugin hands every attribute — static, dynamic, and spread alike — to the runtime `mergeProps` unchanged, and `mergeProps` performs the merge. All three source types are concatenated additively, and each source's value may itself be either a string or an object (e.g. `{ foo: true, bar: isActive() }`); both forms are normalized and merged into the final class list.
 
 In short: introducing a spread in Solid can silently erase previously declared classes; in Plastic the same code keeps all contributions and combines them. This makes host components' class contributions safe under composition without the consumer having to know whether spreads are involved downstream.
 
@@ -128,6 +128,80 @@ The Babel plugin rejects duplicate attribute names on the same JSX element at **
 - **Mount/dispose API**: `renderApp(container, node)` returns an idempotent disposer that unmounts DOM and disposes owner/effect scopes.
 - **Lifecycle hooks**: `onMount` and cleanup registration (`onCleanup` wrapper) are available for component-level setup and teardown.
 
+## JSX Compilation Paths
+
+The `babel-preset-plastic` reactive transform inspects every JSX element and lowers it to one of four runtime shapes. Paths are tried top-to-bottom; the first match wins. Earlier paths are strictly cheaper at runtime, so the transform always picks the most specialized form an element qualifies for.
+
+### 1. Template clone (pure static subtree)
+
+**Trigger:** an entire subtree is "foldable" — intrinsic lowercase tags only, no spread attrs, no namespaced attr names, and **every attribute value and child (recursively) is a scalar literal**. No dynamic holes anywhere.
+
+**Emitted code:**
+```js
+const _tmpl$ = /*#__PURE__*/ template('<div class="row"><span>hello</span></div>')
+// per render site:
+_tmpl$.cloneNode(true)
+```
+
+**Runtime cost per instance:** one native `cloneNode(true)`. The DOM skeleton is parsed once at module load via `innerHTML`; no `createElement`, no per-attribute writes, no per-child append.
+
+### 2. Template clone with holes
+
+**Trigger:** foldable skeleton (same rules as path 1) but with **dynamic attribute values and/or dynamic children**. Static parts fold into the template string; dynamic parts become `setProp` / `insert` ops.
+
+**Emitted code:**
+```js
+const _tmpl$ = template('<div class="row"><span></span></div>')
+// per render site:
+(() => {
+  const _el = _tmpl$.cloneNode(true)
+  const _span = _el.firstChild
+  insert(_span, () => count())
+  return _el
+})()
+```
+
+**Runtime cost per instance:** `cloneNode(true)` + N hole patches. Skips `createElement` and `applyProps` for the static skeleton; only the dynamic holes pay reactive-wrapper cost.
+
+### 3. `jsxStatic` (single element, all-literal attrs)
+
+**Trigger:** lowercase intrinsic tag, no spread, **every attribute value is a scalar literal** (string / number / boolean / null). Children are unconstrained — they pass through the normal `jsx` pipeline as the third argument, so dynamic / component / nested-JSX children are fine. Reached when path 2's whole-subtree foldability declined (typically because babel chose the single-call form for a standalone element).
+
+**Emitted code:**
+```js
+jsxStatic('div', { class: 'row' }, () => count())
+```
+
+**Runtime cost per instance:** `createElement` + one direct DOM write per attribute (no `isReactive` check, no binding-effect wrapper, no `mergeProps` proxy). Children flow through `appendChild`'s usual reactive/defer paths.
+
+### 4. `jsx` / `mergeProps` (general path)
+
+**Trigger:** everything else. In particular:
+- Capitalized tag (`<Foo />`) → component invocation
+- `JSXMemberExpression` (`<obj.Foo />`)
+- `<Dynamic component={...} />`
+- Fragment (`<>...</>`)
+- Intrinsic tag with **any spread attribute**
+- Intrinsic tag with no spread but at least one **non-literal attribute value** (and the subtree wasn't foldable for path 2)
+
+**Emitted code:**
+```js
+jsx(Tag, mergeProps({ class: 'row' }, () => ({ id: id() }), { children: ... }))
+```
+
+**Runtime cost per instance:** full reactive dispatch — `mergeProps` proxy, per-prop `isReactive` / binding-effect wrapping, `applyProps` with `JSX_PROP_MAP` lookups, recursive child handling.
+
+### Summary
+
+| # | Path | Tag | Spread allowed | Attr values | Children | Per-instance work |
+|---|---|---|---|---|---|---|
+| 1 | template (pure) | intrinsic | no | all literal | all literal (recursive) | `cloneNode` |
+| 2 | template + holes | intrinsic | no | any | any | `cloneNode` + hole ops |
+| 3 | `jsxStatic` | intrinsic | no | all scalar literal | any | `createElement` + direct attr writes |
+| 4 | `jsx` / `mergeProps` | any | yes | any | any | full reactive dispatch |
+
+Rule of thumb: **non-intrinsic tags always go through path 4**. The fast paths exist only because lowercase intrinsics map 1:1 to DOM elements and don't need component invocation or descriptor materialization.
+
 ## Reactivity
 
 Plastic's reactivity layer is built on top of [alien-signals](https://github.com/stackblitz/alien-signals) and extends it with deep object reactivity. All primitives are exported from `jsx`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plastic-js/plastic",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "main": "src/index.js",
   "access": "public",
   "sideEffects": false,
@@ -59,7 +59,7 @@
     "@testing-library/jest-dom": "^6.9.1",
     "@vitejs/plugin-react": "^6.0.2",
     "@vitejs/plugin-vue": "^6.0.7",
-    "babel-preset-plastic": "^0.1.5",
+    "babel-preset-plastic": "^0.1.6",
     "eslint": "^9.39.2",
     "eslint-config-janus": "^9.0.21",
     "eslint-plugin-mocha": "^11.3.0",

package/src/jsx-runtime.js

@@ -640,14 +640,17 @@ const disposeBindings = (bindings)=> {
 // free. The value is resolved through `resolveReactiveValue` so signals and
 // zero-arg accessor thunks (used widely by ark-plastic / zag adapters) are
 // unwrapped before being applied to the DOM.
-const bindReactiveProp = (element, props, key)=> {
+const bindReactiveProp = (element, props, key, propsIsTracked)=> {
 	const rawValue = props[key]
 
 	// Static (non-reactive) fast path: write the prop directly with no binding
 	// effect. Most JSX props in real apps are static (className='row', id=...,
 	// type='button' etc.) — building an effect for each one was the biggest
 	// per-component cost in mount benchmarks.
-	if (!isReactive(rawValue)){
+	// Skip the fast path when `props` is itself a tracking proxy (tree /
+	// mergeProps): the value may be a plain string but reading `props[key]`
+	// subscribes through the proxy, so we need an effect to re-run on change.
+	if (!propsIsTracked && !isReactive(rawValue)){
 		let prevStyleValue
 		if (key === 'className' || key === 'class'){
 			applyClassProp(element, rawValue)
@@ -747,6 +750,7 @@ const bindReactiveEvent = (element, props, key)=> {
 // keys later we tear down the previous bindings and rebuild them from the
 // current key set.
 const applyProps = (element, props = {})=> {
+	const propsIsTracked = isMergedProps(props) || isTree(props)
 	const setup = ()=> {
 		const bindings = []
 		// Only register cleanup if there's an owner/computation to attach to.
@@ -778,16 +782,17 @@ const applyProps = (element, props = {})=> {
 				bindings.push(bindReactiveEvent(element, props, key))
 				continue
 			}
-			bindings.push(bindReactiveProp(element, props, key))
+			bindings.push(bindReactiveProp(element, props, key, propsIsTracked))
 		}
 	}
 
 	// Only wrap in an outer binding effect when the proxy has dynamic keys (a
-	// function-typed spread source like `{...api()}`). For static-key proxies
-	// (the common babel reactive transform output with no spreads), and for
-	// plain object props, keys never change — skip the outer effect to avoid
-	// one owner-effect allocation per element.
-	if (isMergedProps(props) && !hasMergedPropsStaticKeys(props)){
+	// function-typed spread source like `{...api()}`, or any tree proxy whose
+	// key set may grow/shrink at runtime). For static-key proxies (the common
+	// babel reactive transform output with no spreads), and for plain object
+	// props, keys never change — skip the outer effect to avoid one
+	// owner-effect allocation per element.
+	if ((isMergedProps(props) && !hasMergedPropsStaticKeys(props)) || isTree(props)){
 		createBindingEffect(setup)
 	} else {
 		setup()
@@ -1224,6 +1229,46 @@ const insert = (parent, accessor, marker = null)=> {
 // change. Class and style go through the existing helpers so the
 // merge/diff semantics stay identical to the JSX path.
 const setProp = (element, key, accessor)=> {
+	// Event handlers (onClick, etc.) — the babel transform emits them as
+	// `() => handler` thunks. Resolve once to the handler and attach a single
+	// listener that re-reads the current accessor at dispatch time (so a signal
+	// returning different handlers stays live without re-attaching).
+	if (isEventProp(key)){
+		const eventName = key.slice(2).toLowerCase()
+		if (!isSupportedEvent(element, eventName)){
+			return
+		}
+		// The babel transform wraps identifier accessors as `() => handler`
+		// (a thunk that returns the real handler), but passes arrow/function
+		// expressions through verbatim (those *are* the handler). Probe once
+		// to figure out which shape we have, then dispatch accordingly.
+		// Re-read each event so identifier-bound handlers stay live if the
+		// outer binding swaps the reference.
+		let useUnwrap = false
+		if (typeof accessor === 'function'){
+			try {
+				const probe = accessor()
+				if (typeof probe === 'function'){
+					useUnwrap = true
+				}
+			} catch {
+				// arrow that throws when called outside of an event — treat as handler
+			}
+		}
+		const listener = (...args)=> {
+			const handler = useUnwrap ? accessor() : accessor
+			if (typeof handler === 'function'){
+				handler(...args)
+			}
+		}
+		element.addEventListener(eventName, listener)
+		if (currentOwner || getCurrentComputation()){
+			registerCleanup(()=> {
+				element.removeEventListener(eventName, listener)
+			})
+		}
+		return
+	}
 	if (typeof accessor !== 'function' || isReactivePrimitive(accessor)){
 		// Reactive primitives (signal/computed) also go through the effect path
 		// so the prop stays in sync — handled in the else branch below.