@plastic-js/plastic 1.0.4 → 1.0.6

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,88 @@ 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 `@plastic-js/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.
+
+The plugin's decision cascade in one line:
+
+```
+if (foldable) { if (ops == 0) cloneNode else IIFE } else if (jsxStatic) ... else generic
+```
+
+Paths 1 and 2 share the same `foldable` branch in the source — they differ only by whether the template has dynamic holes (`plan.ops.length`). Paths 3 and 4 are the remaining `else if` / `else` arms.
+
+### 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`.
@@ -148,6 +230,30 @@ count(1)                             // logs 1
 
 Passing an existing signal returns it unchanged — double-wrapping is a no-op.
 
+##### Signal as a JSX child: prefer `{count}` over `{count()}`
+
+When a signal is used directly as a JSX child, the two forms below are **behaviorally equivalent** — both produce a reactive child that re-renders when the signal updates — but the bare-identifier form is the **recommended** style:
+
+```jsx
+const count = createSignal(0)
+
+<span>{count}</span>     // ✅ Recommended — Identifier passed through as-is (signal is itself a function)
+<span>{count()}</span>   // ⚠️ Discouraged — CallExpression that Babel must wrap as `() => count()`
+```
+
+Why they behave the same:
+
+- The `@plastic-js/babel-preset-plastic` reactive transform classifies identifiers as *static* and emits them unchanged, while call expressions are not static and get wrapped in a thunk (`() => count()`).
+- At runtime, `appendChild` detects any child whose `typeof === 'function'` and routes it through the reactive child path — creating a placeholder, subscribing to signal reads, and patching the DOM on change.
+
+Why prefer `{count}`:
+
+- One fewer function call per update (the `{count()}` form invokes the thunk, which then invokes the signal).
+- Slightly smaller compiled output (no synthesized `() => ...` wrapper).
+- Makes the "signal flows through as a reactive citizen" model explicit at the call site, instead of looking like an eager read.
+
+> This equivalence relies on `count` being a signal (a callable function). For a plain variable (`const count = 2`), `{count}` is a static value and `{count()}` would throw — they are *not* interchangeable in that case.
+
 #### `createComputed(fn)`
 
 Creates a lazily-evaluated derived value. The computation re-runs only when its signal dependencies change.
@@ -244,14 +350,14 @@ toRaw(state)    // { x: 1 }
 
 ### Installation
 
-Install Plastic together with its Babel toolchain. Plastic's JSX compiles in two stages: `@babel/preset-react` turns JSX into `jsx(...)` calls against Plastic's runtime, then `babel-preset-plastic` rewrites those calls for fine-grained reactivity (control-flow lifting, `mergeProps`, etc.).
+Install Plastic together with its Babel toolchain. Plastic's JSX compiles in two stages: `@babel/preset-react` turns JSX into `jsx(...)` calls against Plastic's runtime, then `@plastic-js/babel-preset-plastic` rewrites those calls for fine-grained reactivity (control-flow lifting, `mergeProps`, etc.).
 
 ```bash
 npm install @plastic-js/plastic
 npm install --save-dev \
     @babel/core \
     @babel/preset-react \
-    babel-preset-plastic \
+    @plastic-js/babel-preset-plastic \
     vite-plugin-babel
 ```
 
@@ -260,7 +366,7 @@ Then wire the presets up in `vite.config.js`:
 ```js
 import { defineConfig } from 'vite'
 import babel from 'vite-plugin-babel'
-import plasticJsx from 'babel-preset-plastic'
+import plasticJsx from '@plastic-js/babel-preset-plastic'
 
 export default defineConfig({
     plugins: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plastic-js/plastic",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "main": "src/index.js",
   "access": "public",
   "sideEffects": false,
@@ -51,6 +51,7 @@
   },
   "homepage": "https://github.com/plastic-js/plastic",
   "dependencies": {
+    "@emotion/css": "^11.13.5",
     "alien-signals": "^3.2.1"
   },
   "devDependencies": {
@@ -59,7 +60,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",
+    "@plastic-js/babel-preset-plastic": "^0.1.7",
     "eslint": "^9.39.2",
     "eslint-config-janus": "^9.0.21",
     "eslint-plugin-mocha": "^11.3.0",

package/src/jsx-runtime.js

@@ -624,15 +624,6 @@ const applyRefProp = (element, ref)=> {
 	}
 }
 
-const disposeBindings = (bindings)=> {
-	;[...bindings].reverse().forEach((dispose)=> {
-		if (typeof dispose === 'function'){
-			dispose()
-		}
-	})
-	bindings.length = 0
-}
-
 // Bind a single non-event, non-special prop key to the DOM element. Each
 // individual prop runs inside its own binding effect so a signal change in
 // one prop's getter only re-writes that one attribute. For plain (non-proxy)
@@ -751,41 +742,77 @@ const bindReactiveEvent = (element, props, key)=> {
 // 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.
-		// Allows top-level h() calls outside any component scope (e.g. tests).
-		if (currentOwner || getCurrentComputation()){
-			registerCleanup(()=> {
-				disposeBindings(bindings)
-			})
+	// Per-key disposer map. Re-runs of the outer key-tracking effect diff the
+	// previous and current key set so only added/removed keys touch the DOM;
+	// surviving keys keep their per-prop binding (which already short-circuits
+	// on prev===next inside setDomProp). Tearing down all bindings on every
+	// signal change was the cause of NO-OP attribute thrash on Zag widgets.
+	const bindings = new Map()
+
+	const createBindingForKey = (key)=> {
+		if (key === 'classList'){
+			throw new Error('classList prop is not supported. Use className instead.')
 		}
-
-		for (const key of Reflect.ownKeys(props)){
-			if (typeof key === 'symbol' || key === 'children' || key === 'key'){
-				continue
-			}
-			if (key === 'classList'){
-				throw new Error('classList prop is not supported. Use className instead.')
-			}
+		// Suppress the outer effect's computation context so inner
+		// registerCleanup calls (event listeners, ref nulling) attach to the
+		// owner rather than the outer effect's per-run cleanup list. Otherwise
+		// flushCleanups on the next outer re-run would tear down listeners for
+		// keys we intend to keep.
+		const prevComp = getCurrentComputation()
+		setCurrentComputation(null)
+		try {
 			if (key === 'ref'){
 				const ref = props[key]
 				applyRefProp(element, ref)
-				bindings.push(()=> {
+				return ()=> {
 					if (typeof ref === 'function'){
 						ref(null)
 					}
-				})
-				continue
+				}
 			}
 			if (isEventProp(key)){
-				bindings.push(bindReactiveEvent(element, props, key))
+				return bindReactiveEvent(element, props, key)
+			}
+			return bindReactiveProp(element, props, key, propsIsTracked)
+		} finally {
+			setCurrentComputation(prevComp)
+		}
+	}
+
+	const setup = ()=> {
+		const nextKeys = new Set()
+		for (const key of Reflect.ownKeys(props)){
+			if (typeof key === 'symbol' || key === 'children' || key === 'key'){
 				continue
 			}
-			bindings.push(bindReactiveProp(element, props, key, propsIsTracked))
+			nextKeys.add(key)
+		}
+
+		// Dispose bindings for keys that disappeared. Surviving keys are left
+		// alone — their inner binding effects already react to value changes.
+		for (const [key, dispose] of bindings){
+			if (nextKeys.has(key)) continue
+			if (typeof dispose === 'function') dispose()
+			bindings.delete(key)
+		}
+
+		for (const key of nextKeys){
+			if (bindings.has(key)) continue
+			bindings.set(key, createBindingForKey(key))
 		}
 	}
 
+	// Register full teardown at the owner level (not the outer effect's local
+	// cleanup list) so it fires only on real unmount.
+	if (currentOwner || getCurrentComputation()){
+		registerCleanup(()=> {
+			for (const dispose of bindings.values()){
+				if (typeof dispose === 'function') dispose()
+			}
+			bindings.clear()
+		})
+	}
+
 	// Only wrap in an outer binding effect when the proxy has dynamic keys (a
 	// function-typed spread source like `{...api()}`, or any tree proxy whose
 	// key set may grow/shrink at runtime). For static-key proxies (the common
@@ -1229,6 +1256,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.