ripple 0.3.37 → 0.3.39

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # ripple
 
+## 0.3.39
+
+### Patch Changes
+
+- Updated dependencies []:
+  - ripple@0.3.39
+  - @tsrx/ripple@0.0.21
+
+## 0.3.38
+
+### Patch Changes
+
+- [#1007](https://github.com/Ripple-TS/ripple/pull/1007)
+  [`088299c`](https://github.com/Ripple-TS/ripple/commit/088299ce94a6022c017ce2e56c7e1b59bd5973f7)
+  Thanks [@trueadm](https://github.com/trueadm)! - Keep double-quoted JavaScript
+  strings inside TSRX expression containers using normal JavaScript string
+  semantics while preserving direct double-quoted text child parsing.
+
+- Updated dependencies
+  [[`088299c`](https://github.com/Ripple-TS/ripple/commit/088299ce94a6022c017ce2e56c7e1b59bd5973f7)]:
+  - @tsrx/ripple@0.0.20
+  - ripple@0.3.38
+
 ## 0.3.37
 
 ### 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.37",
+  "version": "0.3.39",
   "type": "module",
   "module": "src/runtime/index-client.js",
   "main": "src/runtime/index-client.js",
@@ -76,7 +76,7 @@
     "esm-env": "^1.2.2",
     "@types/estree": "^1.0.8",
     "@types/estree-jsx": "^1.0.5",
-    "@tsrx/ripple": "0.0.19"
+    "@tsrx/ripple": "0.0.21"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",
@@ -84,9 +84,9 @@
     "typescript": "^5.9.3",
     "@volar/language-core": "~2.4.28",
     "vscode-languageserver-types": "^3.17.5",
-    "@tsrx/core": "0.0.17"
+    "@tsrx/core": "0.0.19"
   },
   "peerDependencies": {
-    "ripple": "0.3.37"
+    "ripple": "0.3.39"
   }
 }

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

@@ -14,6 +14,7 @@ import {
 	TRY_BLOCK,
 	HEAD_BLOCK,
 	DIRECT_CHILD_BLOCK,
+	UNINITIALIZED,
 } from './constants.js';
 import { next_sibling } from './operations.js';
 import { apply_element_spread } from './render.js';
@@ -26,7 +27,9 @@ import {
 	run_block,
 	run_teardown,
 	schedule_update,
+	untrack,
 } from './runtime.js';
+import { is_ripple_object } from './utils.js';
 
 /**
  * @param {Function} fn
@@ -96,29 +99,56 @@ export function branch(fn, flags = 0, state = null) {
 }
 
 /**
+ * Wire up a `{ref expr}` attribute. `expr` may be:
+ *   - a callback function — invoked with the element on mount; if it returns
+ *     a function, that function runs as the cleanup on unmount.
+ *   - 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.
+ *
+ * `get_fn` is invoked through `untrack` so the surrounding render block
+ * doesn't subscribe to whatever the thunk happens to read. The supported
+ * shape is to pass the ref slot itself (`{ref tracker}`); a foot-gun like
+ * `{ref tracker.value}` would otherwise read the cell reactively and cause
+ * spurious re-runs.
+ *
  * @param {Element} element
- * @param {() => (element: Element) => (void | (() => void))} get_fn
+ * @param {() => any} get_fn
+ * @param {(value: any) => void} [set_fn]
  * @returns {Block}
  */
-export function ref(element, get_fn) {
-	/** @type {(element: Element) => (void | (() => void) | undefined)} */
-	var ref_fn;
+export function ref(element, get_fn, set_fn) {
+	// make sure the first run always enters the dispatch branch,
+	/** @type {any} */
+	var ref_value = UNINITIALIZED;
 	/** @type {Block | null} */
 	var e;
 
 	return block(RENDER_BLOCK, () => {
-		if (ref_fn !== (ref_fn = get_fn())) {
+		// avoid any reactive reads
+		var next = untrack(get_fn);
+		if (ref_value !== (ref_value = next)) {
 			if (e) {
 				destroy_block(e);
 				e = null;
 			}
 
-			if (ref_fn) {
+			if (typeof ref_value === 'function') {
+				e = branch(() => {
+					effect(() => ref_value(element));
+				});
+			} else if (is_ripple_object(ref_value)) {
 				e = branch(() => {
 					effect(() => {
-						return ref_fn(element);
+						ref_value.value = element;
+						return () => {
+							ref_value.value = null;
+						};
 					});
 				});
+			} else if (set_fn !== undefined) {
+				set_fn(element);
 			}
 		}
 	});

package/tests/client/ref.test.tsrx

@@ -1,6 +1,7 @@
 import type { PropsWithExtras } from 'ripple';
 import { describe, it, expect } from 'vitest';
-import { RippleArray, createRefKey, flushSync, track } from 'ripple';
+import { RippleArray, createRefKey, effect, flushSync, track } from 'ripple';
+import type { Tracked } from 'ripple';
 
 describe('refs', () => {
 	it('capture a <div>', () => {
@@ -77,6 +78,161 @@ describe('refs', () => {
 		expect(logs).toEqual(['ref called', 'ref called']);
 	});
 
+	it('captures a host element into a Tracked via {ref tracker}', () => {
+		let captured: Tracked<HTMLDivElement | null> | undefined;
+
+		component Component() {
+			const tracker = track<HTMLDivElement | null>(null);
+			captured = tracker;
+
+			<div {ref tracker}>{'Hello World'}</div>
+		}
+
+		render(Component);
+		flushSync();
+		expect(captured!.value).toBeInstanceOf(HTMLDivElement);
+		expect(captured!.value!.textContent).toBe('Hello World');
+	});
+
+	it('forwards a Tracked through a composite component via prop destructuring + spread', () => {
+		let captured: Tracked<HTMLInputElement | null> | undefined;
+
+		component Child({ id, ...rest }: PropsWithExtras<{ id: string }>) {
+			// Symbol-keyed `ref` prop survives `...rest` destructuring and
+			// arrives on the DOM element via spread.
+			<input type="text" {id} {...rest} />
+		}
+
+		component App() {
+			const tracker = track<HTMLInputElement | null>(null);
+			captured = tracker;
+
+			<Child id="example" {ref tracker} />
+		}
+
+		render(App);
+		flushSync();
+		expect(captured!.value).toBeInstanceOf(HTMLInputElement);
+		expect(captured!.value!.id).toBe('example');
+	});
+
+	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 World'}</div>
+
+			// Read the captured element through an effect so the assertion
+			// observes the post-mount value (component setup runs before the
+			// element is created).
+			effect(() => {
+				captured = div ?? null;
+			});
+		}
+
+		render(App);
+		flushSync();
+		expect(captured).toBeInstanceOf(HTMLDivElement);
+		expect(captured!.textContent).toBe('Hello World');
+	});
+
+	it(
+		'uses the function path even when the variable is an Identifier (function wins over setter)',
+		() => {
+			let logs: string[] = [];
+
+			component App() {
+				let cb = (node: HTMLDivElement) => {
+					logs.push(`mount:${node.textContent}`);
+				};
+
+				<div {ref cb}>{'Hello'}</div>
+			}
+
+			render(App);
+			flushSync();
+			expect(logs).toEqual(['mount:Hello']);
+		},
+	);
+
+	it(
+		'uses the Tracked path even when the variable is an Identifier (Tracked wins over setter)',
+		() => {
+			let captured: Tracked<HTMLDivElement | null> | undefined;
+
+			component App() {
+				const tracker = track<HTMLDivElement | null>(null);
+				let slot = tracker;
+				captured = tracker;
+
+				<div {ref slot}>{'Hello'}</div>
+			}
+
+			render(App);
+			flushSync();
+			expect(captured!.value).toBeInstanceOf(HTMLDivElement);
+		},
+	);
+
+	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.
+		let captured: HTMLInputElement | null = null;
+
+		component Child({ id, ...rest }: PropsWithExtras<{ id: string }>) {
+			<input type="text" {id} {...rest} />
+		}
+
+		component App() {
+			let input: HTMLInputElement | undefined;
+
+			<Child id="example" {ref input} />
+
+			effect(() => {
+				captured = input ?? null;
+			});
+		}
+
+		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();
+	});
+
+	it('clears the Tracked when the host element unmounts', () => {
+		let captured: Tracked<HTMLDivElement | null> | undefined;
+		let toggle: Tracked<boolean> | undefined;
+
+		component Component() {
+			const tracker = track<HTMLDivElement | null>(null);
+			const show = track(true);
+			captured = tracker;
+			toggle = show;
+
+			if (show.value) {
+				<div {ref tracker}>{'Hello World'}</div>
+			}
+		}
+
+		render(Component);
+		flushSync();
+		expect(captured!.value).toBeInstanceOf(HTMLDivElement);
+
+		toggle!.value = false;
+		flushSync();
+		expect(captured!.value).toBeNull();
+	});
+
 	it('should handle spreading props with a static ref', () => {
 		let logs: string[] = [];