ripple 0.3.47 → 0.3.49

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # ripple
 
+## 0.3.49
+
+### Patch Changes
+
+- [#1071](https://github.com/Ripple-TS/ripple/pull/1071)
+  [`b54a72f`](https://github.com/Ripple-TS/ripple/commit/b54a72f721adb5f08a5bf3e3d006780b7e1eb471)
+  Thanks [@leonidaz](https://github.com/leonidaz)! - Add named ref props with
+  `prop_name={ref expr}` syntax and expose `isRefProp()` for runtime detection of
+  named ref prop values.
+- Updated dependencies
+  [[`b54a72f`](https://github.com/Ripple-TS/ripple/commit/b54a72f721adb5f08a5bf3e3d006780b7e1eb471),
+  [`b54a72f`](https://github.com/Ripple-TS/ripple/commit/b54a72f721adb5f08a5bf3e3d006780b7e1eb471),
+  [`b54a72f`](https://github.com/Ripple-TS/ripple/commit/b54a72f721adb5f08a5bf3e3d006780b7e1eb471)]:
+  - ripple@0.3.49
+  - @tsrx/core@0.0.28
+  - @tsrx/ripple@0.0.30
+
+## 0.3.48
+
+### Patch Changes
+
+- Updated dependencies []:
+  - ripple@0.3.48
+
 ## 0.3.47
 
 ### Patch Changes

package/package.json

@@ -3,7 +3,7 @@
   "description": "Ripple is an elegant TypeScript UI framework",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.3.47",
+  "version": "0.3.49",
   "type": "module",
   "module": "src/runtime/index-client.js",
   "main": "src/runtime/index-client.js",
@@ -76,17 +76,17 @@
     "esm-env": "^1.2.2",
     "@types/estree": "^1.0.8",
     "@types/estree-jsx": "^1.0.5",
-    "@tsrx/ripple": "0.0.29"
+    "@tsrx/core": "0.0.28",
+    "@tsrx/ripple": "0.0.30"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",
     "@typescript-eslint/types": "^8.40.0",
     "typescript": "^5.9.3",
     "@volar/language-core": "~2.4.28",
-    "vscode-languageserver-types": "^3.17.5",
-    "@tsrx/core": "0.0.27"
+    "vscode-languageserver-types": "^3.17.5"
   },
   "peerDependencies": {
-    "ripple": "0.3.47"
+    "ripple": "0.3.49"
   }
 }

package/src/compiler/types/import.d.ts

@@ -39,6 +39,7 @@ import {
 	RippleDate as _$_Date__Ripple,
 	createRefKey as _$_RefKey__create,
 } from 'ripple';
+import { create_ref_prop as _$_RefProp__create } from '@tsrx/core/runtime/ref';
 
 export {
 	_$_Map__Ripple,
@@ -49,4 +50,5 @@ export {
 	_$_URLSearchParams__Ripple,
 	_$_Date__Ripple,
 	_$_RefKey__create,
+	_$_RefProp__create,
 };

package/src/runtime/index-client.js

@@ -24,7 +24,7 @@ import { COMMENT_NODE, HYDRATION_START } from '../constants.js';
 export { jsx, jsxs, Fragment } from '../jsx-runtime.js';
 export {
 	UNINITIALIZED,
-	DERIVED_UPDATED,
+	TRACKED_UPDATED,
 	SUSPENSE_PENDING,
 	SUSPENSE_REJECTED,
 } from './internal/client/constants.js';
@@ -156,6 +156,8 @@ export { Portal } from './internal/client/portal.js';
 
 export { ref_prop as createRefKey, get, public_set as set } from './internal/client/runtime.js';
 
+export { isRefProp } from '@tsrx/core/runtime/ref';
+
 export { on } from './internal/client/events.js';
 
 export {

package/src/runtime/index-server.js

@@ -12,10 +12,11 @@ export {
 } from './internal/server/index.js';
 export {
 	UNINITIALIZED,
-	DERIVED_UPDATED,
+	TRACKED_UPDATED,
 	SUSPENSE_PENDING,
 	SUSPENSE_REJECTED,
 } from './internal/client/constants.js';
+export { isRefProp } from '@tsrx/core/runtime/ref';
 
 export const effect = noop;
 export const createRefKey = noop;

package/src/runtime/internal/client/bindings.js

@@ -8,7 +8,8 @@
 import { effect, render } from './blocks.js';
 import { on } from './events.js';
 import { get, set } from './runtime.js';
-import { is_array, is_ripple_object } from './utils.js';
+import { is_ripple_object } from './utils.js';
+import { is_array } from '@tsrx/core/runtime/language-helpers';
 
 /**
  * @param {string} name

package/src/runtime/internal/client/blocks.js

@@ -105,7 +105,7 @@ export function branch(fn, flags = 0, state = null) {
  *   - a `Tracked` (e.g. from `track()`) — `tracked.value` is set to the
  *     element on mount and reset to `null` on unmount.
  *   - a plain mutable var (`let foo;`) — the element is assigned to the
- *     variable. No teardown is run, released with the component.
+ *     variable on mount and reset to `null` on unmount.
  *
  * `get_fn` is invoked through `untrack` so the surrounding render block
  * doesn't subscribe to whatever the thunk happens to read. The supported
@@ -148,7 +148,14 @@ export function ref(element, get_fn, set_fn) {
 					});
 				});
 			} else if (set_fn !== undefined) {
-				set_fn(element);
+				e = branch(() => {
+					effect(() => {
+						set_fn(element);
+						return () => {
+							set_fn(null);
+						};
+					});
+				});
 			}
 		}
 	});

package/src/runtime/internal/client/constants.js

@@ -42,7 +42,7 @@ export const NAMESPACE_URI = {
 	mathml: 'http://www.w3.org/1998/Math/MathML',
 };
 /** @type {unique symbol} */
-export const DERIVED_UPDATED = Symbol('derived_updated');
+export const TRACKED_UPDATED = Symbol('TRACKED_UPDATED');
 /** @type {unique symbol} */
 export const SUSPENSE_PENDING = Symbol('suspense_pending');
 /** @type {unique symbol} */

package/src/runtime/internal/client/events.js

@@ -16,7 +16,7 @@ import {
 	set_tracking,
 	tracking,
 } from './runtime.js';
-import { array_from, define_property, is_array } from './utils.js';
+import { array_from, define_property, is_array } from '@tsrx/core/runtime/language-helpers';
 import { render } from './blocks.js';
 
 /** @type {Set<string>} */

package/src/runtime/internal/client/for.js

@@ -6,7 +6,7 @@ import { FOR_BLOCK, TRACKED_ARRAY } from './constants.js';
 import { hydrate_next, hydrate_node, hydrating, set_hydrate_node } from './hydration.js';
 import { create_text, get_first_child, get_last_child, next_sibling } from './operations.js';
 import { active_block, set, tracked, untrack } from './runtime.js';
-import { array_from, is_array } from './utils.js';
+import { array_from, is_array } from '@tsrx/core/runtime/language-helpers';
 
 /**
  * @template V

package/src/runtime/internal/client/html.js

@@ -4,7 +4,7 @@ import { remove_block_dom, render } from './blocks.js';
 import { get_first_child, get_next_sibling } from './operations.js';
 import { active_block } from './runtime.js';
 import { assign_nodes, create_fragment_from_html } from './template.js';
-import { hydrate_next, hydrate_node, hydrating, set_hydrate_node } from './hydration.js';
+import { hydrate_next, hydrating, set_hydrate_node } from './hydration.js';
 import { COMMENT_NODE } from '../../../constants.js';
 
 /**

package/src/runtime/internal/client/index.js

@@ -32,7 +32,7 @@ export {
 
 export {
 	UNINITIALIZED,
-	DERIVED_UPDATED,
+	TRACKED_UPDATED,
 	SUSPENSE_PENDING,
 	SUSPENSE_REJECTED,
 } from './constants.js';
@@ -65,6 +65,7 @@ export {
 	pop_component,
 	untrack,
 	ref_prop,
+	create_ref_prop,
 	fallback,
 	exclude_from_object,
 	derived,
@@ -89,7 +90,7 @@ export { switch_block as switch } from './switch.js';
 
 export { template, append, text } from './template.js';
 
-export { array_slice } from './utils.js';
+export { array_slice } from '@tsrx/core/runtime/language-helpers';
 
 export { ripple_array } from '../../array.js';
 

package/src/runtime/internal/client/operations.js

@@ -1,6 +1,6 @@
 import { TEXT_NODE } from '../../../constants.js';
 import { hydrate_node, hydrating, set_hydrate_node } from './hydration.js';
-import { get_descriptor } from './utils.js';
+import { get_descriptor } from '@tsrx/core/runtime/language-helpers';
 
 /** @type {(() => Node | null)} */
 var first_child_getter;

package/src/runtime/internal/client/portal.js

@@ -5,13 +5,7 @@ import { UNINITIALIZED } from './constants.js';
 import { handle_root_events } from './events.js';
 import { create_text } from './operations.js';
 import { active_block } from './runtime.js';
-import {
-	hydrating,
-	hydrate_next,
-	hydrate_node,
-	set_hydrating,
-	set_hydrate_node,
-} from './hydration.js';
+import { hydrating, hydrate_node, set_hydrating, set_hydrate_node } from './hydration.js';
 import { is_tsrx_element } from '../../element.js';
 
 /**

package/src/runtime/internal/client/render.js

@@ -1,13 +1,14 @@
 /** @import { Block } from '#client' */
 
-import { destroy_block, ref } from './blocks.js';
+import { branch, destroy_block, ref } from './blocks.js';
 import { DESTROYED, REF_PROP } from './constants.js';
+import { isRefProp as is_ref_prop } from '@tsrx/core/runtime/ref';
+import { is_ripple_object } from './utils.js';
 import {
 	get_descriptors,
 	get_own_property_symbols,
 	get_prototype_of,
-	is_ripple_object,
-} from './utils.js';
+} from '@tsrx/core/runtime/language-helpers';
 import { event } from './events.js';
 import {
 	getAttributeEventName as get_attribute_event_name,
@@ -143,11 +144,14 @@ function set_attribute_helper(element, key, value, remove_listeners, prev) {
 		element.classList.add(value);
 	} else if (typeof key === 'string' && is_event_attribute(key)) {
 		// Handle event handlers in spread props
-		const event_name = get_attribute_event_name(key, value);
 		if (remove_listeners[key]) {
 			remove_listeners[key]();
+			remove_listeners[key] = undefined;
+		}
+		if (value != null) {
+			const event_name = get_attribute_event_name(key, value);
+			remove_listeners[key] = event(event_name, element, value);
 		}
-		remove_listeners[key] = event(event_name, element, value);
 	} else {
 		set_attribute(element, key, value);
 	}
@@ -254,56 +258,90 @@ export function set_selected(element, selected) {
 export function apply_element_spread(element, fn) {
 	/** @type {Record<string | symbol, any>} */
 	var prev = {};
-	/** @type {Record<symbol, Block | undefined>} */
+	/** @type {Record<string | symbol, Block | undefined>} */
 	var effects = {};
 	/** @type {Record<string | symbol, (() => void) | undefined>} */
 	var remove_listeners = {};
 
 	/** @type {Record<symbol, any>} */
 	var prev_symbols = {};
+	/** @type {Record<string, any>} */
+	var prev_ref_props = {};
 
 	return () => {
 		var next = fn();
-
-		for (const symbol of get_own_property_symbols(effects)) {
-			if (!next[symbol] && effects[symbol]) {
-				destroy_block(effects[symbol]);
-				effects[symbol] = undefined;
-			}
-		}
-
-		/** @type {Record<symbol, any>} */
-		var current_symbols = {};
+		var current_symbols = /** @type {Record<symbol, any>} */ ({});
 
 		for (const symbol of get_own_property_symbols(next)) {
-			var ref_fn = next[symbol];
+			if (symbol.description !== REF_PROP) {
+				continue;
+			}
+			const ref_fn = next[symbol];
 			current_symbols[symbol] = ref_fn;
 
 			if (
-				symbol.description === REF_PROP &&
-				(!(symbol in prev_symbols) ||
-					ref_fn !== prev_symbols[symbol] ||
-					(effects[symbol] && (effects[symbol].f & DESTROYED) !== 0))
+				!(symbol in prev_symbols) ||
+				ref_fn !== prev_symbols[symbol] ||
+				(effects[symbol] && (effects[symbol].f & DESTROYED) !== 0)
 			) {
 				if (effects[symbol] && (effects[symbol].f & DESTROYED) === 0) {
 					destroy_block(effects[symbol]);
 				}
-				effects[symbol] = ref(element, () => ref_fn);
+				effects[symbol] = create_spread_ref_effect(element, ref_fn);
+			}
+		}
+
+		for (const symbol of get_own_property_symbols(prev_symbols)) {
+			if (!(symbol in current_symbols) && effects[symbol]) {
+				destroy_block(/** @type {Block} */ (effects[symbol]));
+				effects[symbol] = undefined;
 			}
 		}
 
 		prev_symbols = current_symbols;
 
+		/** @type {Record<string, any>} */
+		var current_ref_props = {};
+
+		for (const key in next) {
+			const ref_fn = next[key];
+			if (!is_ref_prop(ref_fn)) {
+				continue;
+			}
+
+			current_ref_props[key] = ref_fn;
+
+			if (
+				!(key in prev_ref_props) ||
+				ref_fn !== prev_ref_props[key] ||
+				(effects[key] && (effects[key].f & DESTROYED) !== 0)
+			) {
+				if (effects[key] && (effects[key].f & DESTROYED) === 0) {
+					destroy_block(effects[key]);
+				}
+				effects[key] = create_spread_ref_effect(element, ref_fn);
+			}
+		}
+
+		for (const key in prev_ref_props) {
+			if (!(key in current_ref_props) && effects[key]) {
+				destroy_block(/** @type {Block} */ (effects[key]));
+				effects[key] = undefined;
+			}
+		}
+
+		prev_ref_props = current_ref_props;
+
 		for (let key in remove_listeners) {
 			// Remove event listeners that are no longer present
-			if (!(key in next) && remove_listeners[key]) {
+			if ((!(key in next) || is_ref_prop(next[key])) && remove_listeners[key]) {
 				remove_listeners[key]();
 				remove_listeners[key] = undefined;
 			}
 		}
 
 		for (const key in prev) {
-			if (!(key in next)) {
+			if (!(key in next) || is_ref_prop(next[key])) {
 				if (key === '#class') {
 					continue;
 				}
@@ -317,6 +355,9 @@ export function apply_element_spread(element, fn) {
 			if (key === 'children') continue;
 
 			let value = next[key];
+			if (is_ref_prop(value)) {
+				continue;
+			}
 			if (is_ripple_object(value)) {
 				value = get(value);
 			}
@@ -331,3 +372,18 @@ export function apply_element_spread(element, fn) {
 		prev = current;
 	};
 }
+
+/**
+ * Keep spread refs in a branch block so ordinary spread updates do not destroy
+ * and recreate the ref block before `apply_element_spread` can compare the
+ * previous and current ref values.
+ *
+ * @param {Element} element
+ * @param {any} ref_fn
+ * @returns {Block}
+ */
+function create_spread_ref_effect(element, ref_fn) {
+	return branch(() => {
+		ref(element, () => ref_fn);
+	});
+}

package/src/runtime/internal/client/runtime.js

@@ -29,7 +29,7 @@ import {
 	REF_PROP,
 	TRACKED_OBJECT,
 	DEFAULT_NAMESPACE,
-	DERIVED_UPDATED,
+	TRACKED_UPDATED,
 	SUSPENSE_PENDING,
 	SUSPENSE_REJECTED,
 	TRY_BLOCK,
@@ -44,18 +44,20 @@ import {
 	register_boundary_paused_block,
 	replace_boundary_request,
 } from './try.js';
+import { is_ripple_object } from './utils.js';
+
 import {
 	define_property,
 	get_descriptor,
 	get_own_property_symbols,
 	is_array,
-	is_ripple_object,
 	object_keys,
-} from './utils.js';
+} from '@tsrx/core/runtime/language-helpers';
 import { get_async_track_result } from '../../../utils/async.js';
 import { get_track_async_script_id } from '../../../utils/track-async-serialization.js';
 import * as devalue from 'devalue';
 import { hydrating, track_hash_reference } from './hydration.js';
+import { create_ref_prop as create_core_ref_prop } from '@tsrx/core/runtime/ref';
 
 const FLUSH_MICROTASK = 0;
 const FLUSH_SYNC = 1;
@@ -668,7 +670,7 @@ export function track_async(fn, b, hash) {
 
 		// Abort previous in-flight request
 		if (abort_controller !== null && abort_controller.signal.aborted === false) {
-			abort_controller.abort(DERIVED_UPDATED);
+			abort_controller.abort(TRACKED_UPDATED);
 		}
 		abort_controller = null;
 
@@ -766,7 +768,7 @@ export function track_async(fn, b, hash) {
 				if (current_version !== version) return; // stale
 
 				var is_internal_abort =
-					error === DERIVED_UPDATED || current_abort_controller?.signal?.reason === DERIVED_UPDATED;
+					error === TRACKED_UPDATED || current_abort_controller?.signal?.reason === TRACKED_UPDATED;
 				if (is_internal_abort) {
 					// Internal abort (superseded by a new request) — don't set rejected
 					if (request_id > 0 && boundary !== null) {
@@ -799,7 +801,7 @@ export function track_async(fn, b, hash) {
 		return () => {
 			// Teardown: abort in-flight request when block is destroyed
 			if (current_abort_controller !== null && current_abort_controller.signal.aborted === false) {
-				current_abort_controller.abort(DERIVED_UPDATED);
+				current_abort_controller.abort(TRACKED_UPDATED);
 			}
 		};
 	});
@@ -1653,6 +1655,15 @@ export function ref_prop() {
 	return Symbol(REF_PROP);
 }
 
+/**
+ * @param {() => any} get_ref_value
+ * @param {(value: any) => void} [set_ref_value]
+ * @returns {(node: any) => void | (() => void)}
+ */
+export function create_ref_prop(get_ref_value, set_ref_value) {
+	return create_core_ref_prop(() => untrack(get_ref_value), set_ref_value);
+}
+
 /**
  * @template T
  * @param {T | undefined} value

package/src/runtime/internal/client/try.js

@@ -9,15 +9,7 @@ import {
 	resume_block,
 } from './blocks.js';
 import { TRY_BLOCK } from './constants.js';
-import {
-	hydrate_next,
-	hydrate_node,
-	hydrating,
-	set_hydrate_node,
-	set_hydrating,
-	skip_to_hydration_end,
-} from './hydration.js';
-import { get_next_sibling } from './operations.js';
+import { hydrate_next, hydrating } from './hydration.js';
 import {
 	active_block,
 	queue_microtask,

package/src/runtime/internal/client/utils.js

@@ -1,44 +1,5 @@
 /** @import { NAMESPACE_URI } from './constants.js' */
 
-/** @type {typeof Object.getOwnPropertyDescriptor} */
-export var get_descriptor = Object.getOwnPropertyDescriptor;
-/** @type {typeof Object.getOwnPropertyDescriptors} */
-export var get_descriptors = Object.getOwnPropertyDescriptors;
-/** @type {typeof Array.from} */
-export var array_from = Array.from;
-/** @type {typeof Array.isArray} */
-export var is_array = Array.isArray;
-/** @type {typeof Object.defineProperty} */
-export var define_property = Object.defineProperty;
-/** @type {typeof Object.getPrototypeOf} */
-export var get_prototype_of = Object.getPrototypeOf;
-/** @type {typeof Object.values} */
-export var object_values = Object.values;
-/** @type {typeof Object.entries} */
-export var object_entries = Object.entries;
-/** @type {typeof Object.keys} */
-export var object_keys = Object.keys;
-/** @type {typeof Object.getOwnPropertySymbols} */
-export var get_own_property_symbols = Object.getOwnPropertySymbols;
-/** @type {typeof structuredClone} */
-export var structured_clone = structuredClone;
-/** @type {typeof Object.prototype} */
-export var object_prototype = Object.prototype;
-/** @type {typeof Array.prototype} */
-export var array_prototype = Array.prototype;
-
-/**
- * Slice helper for arrays and array-like values.
- * @param {ArrayLike<any>} array_like
- * @param {...number} args
- * @returns {any[]}
- */
-export function array_slice(array_like, ...args) {
-	return is_array(array_like)
-		? array_like.slice(...args)
-		: array_prototype.slice.call(array_like, ...args);
-}
-
 /**
  * Creates a text node that serves as an anchor point in the DOM.
  * @returns {Text}

package/src/runtime/internal/server/index.js

@@ -24,14 +24,16 @@ import {
 	SUSPENSE_PENDING,
 	SUSPENSE_REJECTED,
 	ASYNC_DERIVED_READ_THROWN,
-	DERIVED_UPDATED,
+	TRACKED_UPDATED,
 } from '../client/constants.js';
 import { DEV } from 'esm-env';
-import { is_ripple_object, array_slice } from '../client/utils.js';
+import { is_ripple_object } from '../client/utils.js';
+import { array_slice } from '@tsrx/core/runtime/language-helpers';
 import { escape, escapeScript as escape_script } from '@tsrx/core';
 import { isBooleanAttribute as is_boolean_attribute } from '@tsrx/core';
 import { clsx } from 'clsx';
 import { normalizeCssPropertyName as normalize_css_property_name } from '@tsrx/core';
+import { create_ref_prop } from '@tsrx/core/runtime/ref';
 import { BLOCK_CLOSE, BLOCK_OPEN } from '../../../constants.js';
 import { is_tsrx_element, normalize_children, tsrx_element } from '../../element.js';
 import {
@@ -56,6 +58,7 @@ export { context } from './context.js';
 export { try_block, component_block, regular_block } from './blocks.js';
 export { array_slice };
 export { tsrx_element, normalize_children };
+export { create_ref_prop };
 
 /** @extends Error */
 export class TrackAsyncRunError extends Error {
@@ -1566,7 +1569,7 @@ function register_block_rerun(block) {
 		cancel: () => {
 			cancelled = true;
 			if (t && t.aa) {
-				t.aa.abort(DERIVED_UPDATED);
+				t.aa.abort(TRACKED_UPDATED);
 				t.aa = null;
 				t.ap = null;
 			}

package/src/runtime/proxy.js

@@ -8,7 +8,7 @@ import {
 	get_prototype_of,
 	is_array,
 	object_prototype,
-} from './internal/client/utils.js';
+} from '@tsrx/core/runtime/language-helpers';
 import {
 	MAX_ARRAY_LENGTH,
 	TRACKED_ARRAY,

package/tests/client/async-suspend.test.tsrx

@@ -1,5 +1,5 @@
 import type { Tracked } from 'ripple';
-import { DERIVED_UPDATED, effect, flushSync, track, trackAsync } from 'ripple';
+import { TRACKED_UPDATED, effect, flushSync, track, trackAsync } from 'ripple';
 
 describe('async suspense', () => {
 	it('hides child content during re-suspension when tracked dependency changes', async () => {
@@ -115,7 +115,7 @@ describe('async suspense', () => {
 		expect(container.innerHTML).not.toContain('late value');
 	});
 
-	it('aborts superseded requests with DERIVED_UPDATED without rendering catch', async () => {
+	it('aborts superseded requests with TRACKED_UPDATED without rendering catch', async () => {
 		const requests = new Map<
 			string,
 			{ resolve: (value: string) => void; abortController: AbortController }
@@ -181,7 +181,7 @@ describe('async suspense', () => {
 
 		expect(
 			(requests.get('b') as { abortController: AbortController }).abortController.signal.reason,
-		).toBe(DERIVED_UPDATED);
+		).toBe(TRACKED_UPDATED);
 		expect(container.innerHTML).not.toContain('class="error"');
 		expect(container.innerHTML).toContain('value-a');
 

package/tests/client/basic/basic.events.test.tsrx

@@ -123,6 +123,36 @@ describe('basic client > events', () => {
 		expect(countSpan.textContent).toBe('1');
 	});
 
+	it('removes event listeners from spread props when they are replaced by another prop', () => {
+		component Basic() {
+			let &[enabled] = track(true);
+			let &[count] = track(0);
+
+			<button class="target" {...(enabled ? { onClick: () => count++ } : { title: 'disabled' })}>
+				{'target'}
+			</button>
+			<button class="toggle" onClick={() => (enabled = false)}>{'toggle'}</button>
+			<span class="count">{count}</span>
+		}
+
+		render(Basic);
+
+		const target = container.querySelector('.target');
+		const toggle = container.querySelector('.toggle');
+		const count = container.querySelector('.count');
+
+		target.click();
+		flushSync();
+		expect(count.textContent).toBe('1');
+
+		toggle.click();
+		flushSync();
+		expect(target.getAttribute('title')).toBe('disabled');
+		target.click();
+		flushSync();
+		expect(count.textContent).toBe('1');
+	});
+
 	it('handles both delegated and non-delegated events in spread props', () => {
 		component Basic() {
 			let &[clickCount] = track(0);

package/tests/client/dynamic-elements.test.tsrx

@@ -1,5 +1,5 @@
 import type { PropsWithExtras } from 'ripple';
-import { createRefKey, flushSync, track } from 'ripple';
+import { createRefKey, effect, flushSync, track } from 'ripple';
 
 describe('dynamic DOM elements', () => {
 	it('renders static dynamic element', () => {
@@ -225,6 +225,84 @@ describe('dynamic DOM elements', () => {
 		expect(capturedElement!.textContent).toBe('Element with ref');
 	});
 
+	it('handles ref={...}, {ref ...}, and named ref props on dynamic DOM elements', () => {
+		let refAttrElement: HTMLInputElement | null = null;
+		let anonymousRefElement: HTMLInputElement | null = null;
+		let namedRefElement: HTMLInputElement | null = null;
+
+		component App() {
+			let tag = track('input');
+			let input: HTMLInputElement | undefined;
+			const state: { anonymous?: HTMLInputElement } = {};
+
+			<@tag
+				id="dynamic-ref-combo"
+				type="text"
+				ref={input}
+				{ref state.anonymous}
+				input_ref={ref (node: HTMLInputElement | null) => {
+					namedRefElement = node;
+				}}
+			/>
+
+			effect(() => {
+				refAttrElement = input ?? null;
+				anonymousRefElement = state.anonymous ?? null;
+			});
+		}
+
+		render(App);
+		flushSync();
+
+		const element = container.querySelector('#dynamic-ref-combo');
+		expect(element).toBeInstanceOf(HTMLInputElement);
+		expect(refAttrElement).toBe(element);
+		expect(anonymousRefElement).toBe(element);
+		expect(namedRefElement).toBe(element);
+		expect(element!.hasAttribute('ref')).toBe(false);
+		expect(element!.hasAttribute('input_ref')).toBe(false);
+	});
+
+	it('forwards dynamic ref forms through a dynamic component that spreads props', () => {
+		let refAttrElement: HTMLInputElement | null = null;
+		let anonymousRefElement: HTMLInputElement | null = null;
+		let namedRefElement: HTMLInputElement | null = null;
+
+		component Child(props: PropsWithExtras<{}>) {
+			<input id="dynamic-component-ref-combo" type="text" {...props} />
+		}
+
+		component App() {
+			let dynamic = track(() => Child);
+			let input: HTMLInputElement | undefined;
+			const state: { anonymous?: HTMLInputElement } = {};
+
+			<@dynamic
+				ref={input}
+				{ref state.anonymous}
+				input_ref={ref (node: HTMLInputElement | null) => {
+					namedRefElement = node;
+				}}
+			/>
+
+			effect(() => {
+				refAttrElement = input ?? null;
+				anonymousRefElement = state.anonymous ?? null;
+			});
+		}
+
+		render(App);
+		flushSync();
+
+		const element = container.querySelector('#dynamic-component-ref-combo');
+		expect(element).toBeInstanceOf(HTMLInputElement);
+		expect(refAttrElement).toBe(element);
+		expect(anonymousRefElement).toBe(element);
+		expect(namedRefElement).toBe(element);
+		expect(element!.hasAttribute('ref')).toBe(false);
+		expect(element!.hasAttribute('input_ref')).toBe(false);
+	});
+
 	it('handles dynamic element with createRefKey in spread', () => {
 		component App() {
 			let tag = track('header');

package/tests/client/ref.test.tsrx

@@ -1,9 +1,70 @@
 import type { PropsWithExtras } from 'ripple';
 import { describe, it, expect } from 'vitest';
-import { RippleArray, createRefKey, effect, flushSync, track } from 'ripple';
+import { RippleArray, createRefKey, effect, flushSync, isRefProp, track } from 'ripple';
 import type { Tracked } from 'ripple';
 
 describe('refs', () => {
+	it('reports ordinary functions and ref objects as non named-ref props', () => {
+		expect(isRefProp(() => {})).toBe(false);
+		expect(isRefProp({ current: null })).toBe(false);
+		expect(isRefProp({ value: null })).toBe(false);
+	});
+
+	it('captures a host element with a named ref prop', () => {
+		let captured: HTMLInputElement | null = null;
+
+		component App() {
+			let input: HTMLInputElement | undefined;
+
+			<input type="text" input_ref={ref input} />
+
+			effect(() => {
+				captured = input ?? null;
+			});
+		}
+
+		render(App);
+		flushSync();
+
+		expect(captured).toBeInstanceOf(HTMLInputElement);
+	});
+
+	it('forwards a named ref prop explicitly through a component', () => {
+		let captured: HTMLInputElement | null = null;
+
+		component Child(props: PropsWithExtras<{}>) {
+			expect(isRefProp(props.input_ref)).toBe(true);
+			<input type="text" ref={props.input_ref} />
+		}
+
+		component App() {
+			<Child input_ref={ref (node: HTMLInputElement | null) => (captured = node)} />
+		}
+
+		render(App);
+		flushSync();
+
+		expect(captured).toBeInstanceOf(HTMLInputElement);
+	});
+
+	it('applies named ref props from host spreads', () => {
+		let captured: HTMLInputElement | null = null;
+
+		component Child(props: PropsWithExtras<{}>) {
+			expect(isRefProp(props.input_ref)).toBe(true);
+			<input type="text" {...props} />
+		}
+
+		component App() {
+			<Child input_ref={ref (node: HTMLInputElement | null) => (captured = node)} />
+		}
+
+		render(App);
+		flushSync();
+
+		expect(captured).toBeInstanceOf(HTMLInputElement);
+	});
+
 	it('capture a <div>', () => {
 		let div: HTMLDivElement | undefined;
 
@@ -138,6 +199,95 @@ describe('refs', () => {
 		expect(captured!.textContent).toBe('Hello World');
 	});
 
+	it('assigns a host element to a plain let variable via ref={var}', () => {
+		let captured: HTMLDivElement | null = null;
+
+		component App() {
+			let div: HTMLDivElement | undefined;
+
+			<div ref={div}>{'Hello ref attr'}</div>
+
+			effect(() => {
+				captured = div ?? null;
+			});
+		}
+
+		render(App);
+		flushSync();
+		expect(captured).toBeInstanceOf(HTMLDivElement);
+		expect(captured!.textContent).toBe('Hello ref attr');
+	});
+
+	it('clears a plain let variable via ref={var} when the host element unmounts', () => {
+		let div: HTMLDivElement | null | undefined;
+
+		component App() {
+			let &[show] = track(true);
+
+			if (show) {
+				<div ref={div}>{'Hello cleanup'}</div>
+			}
+
+			<button class="toggle" onClick={() => (show = false)}>{'hide'}</button>
+		}
+
+		render(App);
+		flushSync();
+		expect(div).toBeInstanceOf(HTMLDivElement);
+
+		(container.querySelector('.toggle') as HTMLButtonElement).click();
+		flushSync();
+		expect(div).toBeNull();
+	});
+
+	it('assigns a host element to a member expression via ref={state.var}', () => {
+		let captured: HTMLInputElement | null = null;
+
+		component App() {
+			const state: { input?: HTMLInputElement } = {};
+
+			<input type="text" ref={state.input} />
+
+			effect(() => {
+				captured = state.input ?? null;
+			});
+		}
+
+		render(App);
+		flushSync();
+		expect(captured).toBeInstanceOf(HTMLInputElement);
+	});
+
+	it('clears a plain let variable via component ref={var} when the host element unmounts', () => {
+		let input: HTMLInputElement | null | undefined;
+		let previous: HTMLInputElement | undefined;
+
+		component Child(props: PropsWithExtras<{}>) {
+			<input type="text" value="keep" {...props} />
+		}
+
+		component App() {
+			let &[show] = track(true);
+
+			if (show) {
+				<Child ref={input} />
+			}
+
+			<button class="toggle" onClick={() => (show = false)}>{'hide'}</button>
+		}
+
+		render(App);
+		flushSync();
+		expect(input).toBeInstanceOf(HTMLInputElement);
+		previous = input!;
+		expect(previous.value).toBe('keep');
+
+		(container.querySelector('.toggle') as HTMLButtonElement).click();
+		flushSync();
+		expect(input).toBeNull();
+		expect(previous.value).toBe('keep');
+	});
+
 	it(
 		'uses the function path even when the variable is an Identifier (function wins over setter)',
 		() => {
@@ -176,14 +326,7 @@ describe('refs', () => {
 		},
 	);
 
-	it('does NOT propagate a plain let variable through a composite component via {...rest}', () => {
-		// Assignment-sugar (`let foo; <el {ref foo} />`) only works on
-		// host elements, where the setter closure has direct lexical
-		// access to the parent's slot. Passing a plain `let` variable
-		// through a composite forwards only its current value into the
-		// child's local prop bag — there is no slot identity across the
-		// component boundary. Use a `Tracked` (object identity) when you
-		// need the captured node to be visible in the parent.
+	it('propagates a plain let variable through a composite component via {...rest}', () => {
 		let captured: HTMLInputElement | null = null;
 
 		component Child({ id, ...rest }: PropsWithExtras<{ id: string }>) {
@@ -202,11 +345,108 @@ describe('refs', () => {
 
 		render(App);
 		flushSync();
-		// The DOM input was created and exists — but the parent's `input`
-		// slot stays unset because there is no setter to forward through
-		// the composite boundary.
 		expect(container.querySelector('input')).toBeInstanceOf(HTMLInputElement);
-		expect(captured).toBeNull();
+		expect(captured).toBeInstanceOf(HTMLInputElement);
+		expect(captured!.id).toBe('example');
+	});
+
+	it(
+		'clears a plain let variable forwarded through a named ref prop when the host element unmounts',
+		() => {
+			let input: HTMLInputElement | null | undefined;
+			let previous: HTMLInputElement | undefined;
+
+			component Child(props: PropsWithExtras<{}>) {
+				<input type="text" value="keep" {...props} />
+			}
+
+			component App() {
+				let &[show] = track(true);
+
+				if (show) {
+					<Child input_ref={ref input} />
+				}
+
+				<button class="toggle" onClick={() => (show = false)}>{'hide'}</button>
+			}
+
+			render(App);
+			flushSync();
+			expect(input).toBeInstanceOf(HTMLInputElement);
+			previous = input!;
+			expect(previous.value).toBe('keep');
+
+			(container.querySelector('.toggle') as HTMLButtonElement).click();
+			flushSync();
+			expect(input).toBeNull();
+			expect(previous.value).toBe('keep');
+		},
+	);
+
+	it('clears a named ref prop when a host spread changes it to a regular prop', () => {
+		let input: HTMLInputElement | null | undefined;
+		let previous: HTMLInputElement | undefined;
+
+		component Child(props: PropsWithExtras<{}>) {
+			let &[as_ref] = track(true);
+
+			<input
+				type="text"
+				value="keep"
+				{...(as_ref ? { input_ref: props.input_ref } : { input_ref: 'regular prop' })}
+			/>
+			<button class="toggle" onClick={() => (as_ref = false)}>{'toggle'}</button>
+		}
+
+		component App() {
+			<Child input_ref={ref input} />
+		}
+
+		render(App);
+		flushSync();
+		expect(input).toBeInstanceOf(HTMLInputElement);
+		previous = input!;
+		expect(previous.value).toBe('keep');
+		expect(previous.getAttribute('input_ref')).toBeNull();
+
+		(container.querySelector('.toggle') as HTMLButtonElement).click();
+		flushSync();
+		expect(input).toBeNull();
+		expect(previous.value).toBe('keep');
+		expect(previous.getAttribute('input_ref')).toBe('regular prop');
+	});
+
+	it('removes a regular spread attribute when the key changes to a named ref prop', () => {
+		let input: HTMLInputElement | null | undefined;
+		let previous: HTMLInputElement | undefined;
+
+		component Child(props: PropsWithExtras<{}>) {
+			let &[as_ref] = track(false);
+
+			<input
+				type="text"
+				value="keep"
+				{...(as_ref ? { input_ref: props.input_ref } : { input_ref: 'regular prop' })}
+			/>
+			<button class="toggle" onClick={() => (as_ref = true)}>{'toggle'}</button>
+		}
+
+		component App() {
+			<Child input_ref={ref input} />
+		}
+
+		render(App);
+		flushSync();
+		expect(input).toBeUndefined();
+		previous = container.querySelector('input') as HTMLInputElement;
+		expect(previous.value).toBe('keep');
+		expect(previous.getAttribute('input_ref')).toBe('regular prop');
+
+		(container.querySelector('.toggle') as HTMLButtonElement).click();
+		flushSync();
+		expect(input).toBe(previous);
+		expect(previous.value).toBe('keep');
+		expect(previous.getAttribute('input_ref')).toBeNull();
 	});
 
 	it('clears the Tracked when the host element unmounts', () => {

package/types/index.d.ts

@@ -146,8 +146,10 @@ declare global {
 
 export function createRefKey(): symbol;
 
+export function isRefProp(value: unknown): boolean;
+
 export const UNINITIALIZED: unique symbol;
-export const DERIVED_UPDATED: unique symbol;
+export const TRACKED_UPDATED: unique symbol;
 export const SUSPENSE_PENDING: unique symbol;
 export const SUSPENSE_REJECTED: unique symbol;