ripple 0.2.171 → 0.2.173

package/package.json

@@ -3,7 +3,7 @@
   "description": "Ripple is an elegant TypeScript UI framework",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.2.171",
+  "version": "0.2.173",
   "type": "module",
   "module": "src/runtime/index-client.js",
   "main": "src/runtime/index-client.js",
@@ -81,6 +81,6 @@
     "typescript": "^5.9.2"
   },
   "peerDependencies": {
-    "ripple": "0.2.171"
+    "ripple": "0.2.173"
   }
 }

package/src/runtime/index-client.js

@@ -88,6 +88,7 @@ export {
 	bindContentBoxSize,
 	bindBorderBoxSize,
 	bindDevicePixelContentBoxSize,
+	bindFiles,
 	bindIndeterminate,
 	bindInnerHTML,
 	bindInnerText,

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

@@ -311,32 +311,28 @@ export function bindGroup(maybe_tracked) {
 	return (input) => {
 		var is_checkbox = input.getAttribute('type') === 'checkbox';
 
-		// Store the input's value
-		// @ts-ignore
-		input.__value = input.value;
-
 		var clear_event = on(input, 'change', () => {
-			// @ts-ignore
-			var value = input.__value;
+			var value = input.value;
+			var result;
 
 			if (is_checkbox) {
 				/** @type {Array<any>} */
-				var current_value = get(tracked) || [];
+				var list = get(tracked) || [];
 
 				if (input.checked) {
-					// Add if not already present
-					if (!current_value.includes(value)) {
-						value = [...current_value, value];
+					if (!list.includes(value)) {
+						result = [...list, value];
 					} else {
-						value = current_value;
+						result = list;
 					}
 				} else {
-					// Remove the value
-					value = current_value.filter((v) => v !== value);
+					result = list.filter((v) => v !== value);
 				}
+			} else {
+				result = input.value;
 			}
 
-			set(tracked, value);
+			set(tracked, result);
 		});
 
 		effect(() => {
@@ -344,11 +340,9 @@ export function bindGroup(maybe_tracked) {
 
 			if (is_checkbox) {
 				value = value || [];
-				// @ts-ignore
-				input.checked = value.includes(input.__value);
+				input.checked = value.includes(input.value);
 			} else {
-				// @ts-ignore
-				input.checked = value === input.__value;
+				input.checked = value === input.value;
 			}
 		});
 
@@ -530,6 +524,24 @@ export function bindTextContent(maybe_tracked) {
 	return bind_content_editable(maybe_tracked, 'textContent');
 }
 
+/**
+ * @param {unknown} maybe_tracked
+ * @returns {(node: HTMLInputElement) => void}
+ */
+export function bindFiles(maybe_tracked) {
+	if (!is_tracked_object(maybe_tracked)) {
+		throw not_tracked_type_error('bindFiles()');
+	}
+
+	const tracked = /** @type {Tracked} */ (maybe_tracked);
+
+	return (input) => {
+		return on(input, 'change', () => {
+			set(tracked, input.files);
+		});
+	};
+}
+
 /**
  * Syntactic sugar for binding a HTMLElement with {ref fn}
  * @param {unknown} maybe_tracked

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

@@ -163,7 +163,13 @@ export function handle_event_propagation(event) {
 				var delegated = current_target['__' + event_name];
 
 				if (delegated !== undefined && !(/** @type {any} */ (current_target).disabled)) {
-					delegated.call(current_target, event);
+					if (is_array(delegated)) {
+						for (var i = 0; i < delegated.length; i++) {
+							delegated[i].call(current_target, event);
+						}
+					} else {
+						delegated.call(current_target, event);
+					}
 				}
 			} catch (error) {
 				if (throw_error) {
@@ -235,10 +241,31 @@ function create_event(event_name, dom, handler, options) {
 
 	if (is_delegated) {
 		var prop = '__' + event_name;
-		/** @type {DelegatedEventTarget} */ (dom)[prop] = handler;
+		var target = /** @type {DelegatedEventTarget} */ (dom);
+		var current = target[prop];
+
+		if (current === undefined) {
+			target[prop] = handler;
+		} else if (is_array(current)) {
+			if (!current.includes(handler)) {
+				current.push(handler);
+			}
+		} else {
+			if (current !== handler) {
+				target[prop] = [current, handler];
+			}
+		}
+
 		delegate([event_name]);
 		return () => {
-			/** @type {DelegatedEventTarget} */ (dom)[prop] = undefined;
+			var handlers = target[prop];
+			if (is_array(handlers)) {
+				var filtered = handlers.filter((h) => h !== handler);
+				target[prop] =
+					filtered.length === 0 ? undefined : filtered.length === 1 ? filtered[0] : filtered;
+			} else {
+				target[prop] = undefined;
+			}
 		};
 	}
 

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

@@ -129,7 +129,7 @@ function apply_styles(element, new_styles, prev) {
  * @param {string} key
  * @param {any} value
  * @param {Record<string, (() => void) | undefined>} remove_listeners
- * @param {Record<string, any>} prev
+ * @param {Record<string | symbol, any>} prev
  */
 function set_attribute_helper(element, key, value, remove_listeners, prev) {
 	if (key === 'class') {

package/tests/client/events.test.ripple

@@ -0,0 +1,562 @@
+import { track, flushSync, on } from 'ripple';
+
+describe('on() event handler', () => {
+	it('should attach multiple handlers via onClick attribute (delegated)', () => {
+		component Basic() {
+			let count1 = track(0);
+			let count2 = track(0);
+
+			<button
+				onClick={() => {
+					@count1++;
+					@count2++;
+				}}
+			>
+				{'Click me'}
+			</button>
+			<div class="count1">{@count1}</div>
+			<div class="count2">{@count2}</div>
+		}
+
+		render(Basic);
+
+		const button = container.querySelector('button');
+		const count1Div = container.querySelector('.count1');
+		const count2Div = container.querySelector('.count2');
+
+		expect(count1Div.textContent).toBe('0');
+		expect(count2Div.textContent).toBe('0');
+
+		button.click();
+		flushSync();
+		expect(count1Div.textContent).toBe('1');
+		expect(count2Div.textContent).toBe('1');
+	});
+
+	it('should attach and remove a single event handler', () => {
+		component Basic() {
+			let count = track(0);
+
+			const setupListener = (node) => {
+				const remove = on(node, 'click', () => {
+					@count++;
+				});
+				return remove;
+			};
+			<button {ref setupListener}>{'Click me'}</button>
+			<div class="count">{@count}</div>
+		}
+
+		render(Basic);
+		flushSync();
+
+		const button = container.querySelector('button');
+		const countDiv = container.querySelector('.count');
+
+		expect(countDiv.textContent).toBe('0');
+
+		button.click();
+		flushSync();
+		expect(countDiv.textContent).toBe('1');
+
+		button.click();
+		flushSync();
+		expect(countDiv.textContent).toBe('2');
+	});
+
+	it('should handle multiple different event types on same element', () => {
+		component Basic() {
+			let clickCount = track(0);
+			let mousedownCount = track(0);
+
+			const setupListeners = (node) => {
+				const remove1 = on(node, 'click', () => {
+					@clickCount++;
+				});
+				const remove2 = on(node, 'mousedown', () => {
+					@mousedownCount++;
+				});
+				return () => {
+					remove1();
+					remove2();
+				};
+			};
+			<button {ref setupListeners}>{'Test'}</button>
+			<div class="click-count">{@clickCount}</div>
+			<div class="mousedown-count">{@mousedownCount}</div>
+		}
+
+		render(Basic);
+		flushSync();
+
+		const button = container.querySelector('button');
+		const clickDiv = container.querySelector('.click-count');
+		const mousedownDiv = container.querySelector('.mousedown-count');
+
+		expect(clickDiv.textContent).toBe('0');
+		expect(mousedownDiv.textContent).toBe('0');
+
+		button.click();
+		flushSync();
+		expect(clickDiv.textContent).toBe('1');
+		expect(mousedownDiv.textContent).toBe('0'); // click() doesn't trigger mousedown
+
+		button.dispatchEvent(new MouseEvent('mousedown', { bubbles: true }));
+		flushSync();
+		expect(clickDiv.textContent).toBe('1');
+		expect(mousedownDiv.textContent).toBe('1');
+
+		// Click again to verify both handlers still work
+		button.click();
+		flushSync();
+		expect(clickDiv.textContent).toBe('2');
+		expect(mousedownDiv.textContent).toBe('1'); // Still only incremented by mousedown events
+	});
+
+	it('should handle multiple handlers for same event type on same element', () => {
+		component Basic() {
+			let callOrder = track<number[]>([]);
+
+			const setupListeners = (node) => {
+				const remove1 = on(node, 'click', () => {
+					@callOrder = [...@callOrder, 1];
+				});
+				const remove2 = on(node, 'click', () => {
+					@callOrder = [...@callOrder, 2];
+				});
+				const remove3 = on(node, 'click', () => {
+					@callOrder = [...@callOrder, 3];
+				});
+				return () => {
+					remove1();
+					remove2();
+					remove3();
+				};
+			};
+			<button {ref setupListeners}>{'Click me'}</button>
+			<div class="order">{@callOrder.join(',')}</div>
+		}
+
+		render(Basic);
+		flushSync();
+
+		const button = container.querySelector('button');
+		const orderDiv = container.querySelector('.order');
+
+		expect(orderDiv.textContent).toBe('');
+
+		button.click();
+		flushSync();
+		expect(orderDiv.textContent).toBe('1,2,3');
+
+		// Click again to verify order is consistent
+		button.click();
+		flushSync();
+		expect(orderDiv.textContent).toBe('1,2,3,1,2,3');
+	});
+
+	it('should remove specific handler without affecting others', () => {
+		component Basic() {
+			let handler1Called = track(0);
+			let handler2Called = track(0);
+			let handler3Called = track(0);
+			let removeHandler2;
+
+			const setupListeners = (node) => {
+				const remove1 = on(node, 'click', () => {
+					@handler1Called++;
+				});
+				removeHandler2 = on(node, 'click', () => {
+					@handler2Called++;
+				});
+				const remove3 = on(node, 'click', () => {
+					@handler3Called++;
+				});
+				return () => {
+					remove1();
+					removeHandler2?.();
+					remove3();
+				};
+			};
+			<div>
+				<button class="test-btn" {ref setupListeners}>{'Click me'}</button>
+				<button
+					class="remove-btn"
+					onClick={() => {
+						removeHandler2?.();
+						removeHandler2 = undefined;
+					}}
+				>
+					{'Remove handler 2'}
+				</button>
+				<div class="h1">{@handler1Called}</div>
+				<div class="h2">{@handler2Called}</div>
+				<div class="h3">{@handler3Called}</div>
+			</div>
+		}
+
+		render(Basic);
+		flushSync();
+
+		const testBtn = container.querySelector('.test-btn');
+		const removeBtn = container.querySelector('.remove-btn');
+		const h1Div = container.querySelector('.h1');
+		const h2Div = container.querySelector('.h2');
+		const h3Div = container.querySelector('.h3');
+
+		// All handlers should be called initially
+		testBtn.click();
+		flushSync();
+		expect(h1Div.textContent).toBe('1');
+		expect(h2Div.textContent).toBe('1');
+		expect(h3Div.textContent).toBe('1');
+
+		// Remove handler 2
+		removeBtn.click();
+		flushSync();
+
+		// Only handlers 1 and 3 should be called
+		testBtn.click();
+		flushSync();
+		expect(h1Div.textContent).toBe('2');
+		expect(h2Div.textContent).toBe('1'); // Should not increment
+		expect(h3Div.textContent).toBe('2');
+
+		// Verify again
+		testBtn.click();
+		flushSync();
+		expect(h1Div.textContent).toBe('3');
+		expect(h2Div.textContent).toBe('1'); // Still should not increment
+		expect(h3Div.textContent).toBe('3');
+	});
+
+	it(
+		'should handle change event with multiple handlers (like bindChecked and bindIndeterminate)',
+		() => {
+			component Basic() {
+				let checked = track(false);
+				let indeterminate = track(true);
+
+				const setupListeners = (node) => {
+					node.indeterminate = @indeterminate;
+					node.checked = @checked;
+
+					const remove1 = on(node, 'change', () => {
+						@checked = node.checked;
+					});
+					const remove2 = on(node, 'change', () => {
+						@indeterminate = node.indeterminate;
+					});
+					return () => {
+						remove1();
+						remove2();
+					};
+				};
+				<div>
+					<input type="checkbox" {ref setupListeners} />
+					<div class="checked">{@checked ? 'true' : 'false'}</div>
+					<div class="indeterminate">{@indeterminate ? 'true' : 'false'}</div>
+				</div>
+			}
+
+			render(Basic);
+			flushSync();
+
+			const input = container.querySelector('input');
+			const checkedDiv = container.querySelector('.checked');
+			const indeterminateDiv = container.querySelector('.indeterminate');
+
+			expect(checkedDiv.textContent).toBe('false');
+			expect(indeterminateDiv.textContent).toBe('true');
+			expect(input.indeterminate).toBe(true);
+
+			// Click the checkbox
+			input.click();
+			flushSync();
+
+			// Both tracked values should update
+			expect(checkedDiv.textContent).toBe('true');
+			expect(indeterminateDiv.textContent).toBe('false');
+		},
+	);
+
+	it('should support non-delegated events', () => {
+		component Basic() {
+			let focusCount = track(0);
+
+			const setupListener = (node) => {
+				const remove = on(node, 'focus', () => {
+					@focusCount++;
+				});
+				return remove;
+			};
+
+			<input {ref setupListener} />
+			<div class="focus-count">{@focusCount}</div>
+		}
+
+		render(Basic);
+		flushSync();
+
+		const input = container.querySelector('input');
+		const focusDiv = container.querySelector('.focus-count');
+
+		expect(focusDiv.textContent).toBe('0');
+
+		input.dispatchEvent(new Event('focus'));
+		flushSync();
+		expect(focusDiv.textContent).toBe('1');
+
+		input.dispatchEvent(new Event('focus'));
+		flushSync();
+		expect(focusDiv.textContent).toBe('2');
+	});
+
+	it('should handle removal of all handlers for same event type', () => {
+		component Basic() {
+			let count = track(0);
+			let remove1, remove2, remove3;
+
+			const setupListeners = (node) => {
+				remove1 = on(node, 'click', () => {
+					@count++;
+				});
+				remove2 = on(node, 'click', () => {
+					@count += 10;
+				});
+				remove3 = on(node, 'click', () => {
+					@count += 100;
+				});
+				return () => {
+					remove1?.();
+					remove2?.();
+					remove3?.();
+				};
+			};
+			<div>
+				<button class="test-btn" {ref setupListeners}>{'Click me'}</button>
+				<button
+					class="remove-all"
+					onClick={() => {
+						remove1?.();
+						remove2?.();
+						remove3?.();
+						remove1 = remove2 = remove3 = undefined;
+					}}
+				>
+					{'Remove all'}
+				</button>
+				<div class="count">{@count}</div>
+			</div>
+		}
+
+		render(Basic);
+		flushSync();
+
+		const testBtn = container.querySelector('.test-btn');
+		const removeAllBtn = container.querySelector('.remove-all');
+		const countDiv = container.querySelector('.count');
+
+		expect(countDiv.textContent).toBe('0');
+
+		// All three handlers should fire (1 + 10 + 100 = 111)
+		testBtn.click();
+		flushSync();
+		expect(countDiv.textContent).toBe('111');
+
+		// Remove all handlers
+		removeAllBtn.click();
+		flushSync();
+
+		// No handlers should fire
+		testBtn.click();
+		flushSync();
+		expect(countDiv.textContent).toBe('111'); // Should remain unchanged
+	});
+
+	it('should not add duplicate handlers when same handler is attached multiple times', () => {
+		component Basic() {
+			let count = track(0);
+
+			const sharedHandler = () => {
+				@count++;
+			};
+
+			const setupListeners = (node) => {
+				// Attach the same handler multiple times
+				const remove1 = on(node, 'click', sharedHandler);
+				const remove2 = on(node, 'click', sharedHandler);
+				const remove3 = on(node, 'click', sharedHandler);
+
+				return () => {
+					remove1?.();
+					remove2?.();
+					remove3?.();
+				};
+			};
+
+			<button {ref setupListeners}>{'Click me'}</button>
+			<div class="count">{@count}</div>
+		}
+
+		render(Basic);
+		flushSync();
+
+		const button = container.querySelector('button');
+		const countDiv = container.querySelector('.count');
+
+		expect(countDiv.textContent).toBe('0');
+
+		// Handler should only be called once per click, not three times
+		button.click();
+		flushSync();
+		expect(countDiv.textContent).toBe('1');
+
+		button.click();
+		flushSync();
+		expect(countDiv.textContent).toBe('2');
+	});
+
+	it('should allow duplicate handlers when delegated is false (no deduplication)', () => {
+		component Basic() {
+			let count = track(0);
+
+			const sharedHandler = () => {
+				@count++;
+			};
+
+			const setupListeners = (node) => {
+				// Attach the same handler multiple times with delegated: false
+				const remove1 = on(node, 'click', sharedHandler, { delegated: false });
+				const remove2 = on(node, 'click', sharedHandler, { delegated: false });
+				const remove3 = on(node, 'click', sharedHandler, { delegated: false });
+
+				return () => {
+					remove1?.();
+					remove2?.();
+					remove3?.();
+				};
+			};
+
+			<button {ref setupListeners}>{'Click me'}</button>
+			<div class="count">{@count}</div>
+		}
+
+		render(Basic);
+		flushSync();
+
+		const button = container.querySelector('button');
+		const countDiv = container.querySelector('.count');
+
+		expect(countDiv.textContent).toBe('0');
+
+		// Non-delegated events use addEventListener directly, which DOES allow duplicates
+		// So handler should be called 3 times per click
+		button.click();
+		flushSync();
+		expect(countDiv.textContent).toBe('3');
+
+		button.click();
+		flushSync();
+		expect(countDiv.textContent).toBe('6');
+	});
+
+	it('should fire capture event on parent before bubbling event on child', () => {
+		component Basic() {
+			let callOrder = track<string[]>([]);
+
+			const parentCaptureHandler = () => {
+				@callOrder = [...@callOrder, 'parent-capture'];
+			};
+
+			const childBubbleHandler = () => {
+				@callOrder = [...@callOrder, 'child-bubble'];
+			};
+
+			const setupParent = (node) => {
+				return on(node, 'clickCapture', parentCaptureHandler);
+			};
+
+			const setupChild = (node) => {
+				return on(node, 'click', childBubbleHandler);
+			};
+
+			<div {ref setupParent} class="parent">
+				<button {ref setupChild} class="child">{'Click me'}</button>
+			</div>
+			<div class="order">{@callOrder.join(',')}</div>
+		}
+
+		render(Basic);
+		flushSync();
+
+		const button = container.querySelector('.child');
+		const orderDiv = container.querySelector('.order');
+
+		expect(orderDiv.textContent).toBe('');
+
+		// Capture phase happens first (parent), then bubbling phase (child)
+		button.click();
+		flushSync();
+		expect(orderDiv.textContent).toBe('parent-capture,child-bubble');
+
+		// Click again to verify order is consistent
+		button.click();
+		flushSync();
+		expect(orderDiv.textContent).toBe('parent-capture,child-bubble,parent-capture,child-bubble');
+	});
+
+	it('should fire handler only once when once option is true', () => {
+		component Basic() {
+			let count = track(0);
+			let permanentCount = track(0);
+
+			const setupListeners = (node) => {
+				const onceHandler = on(node, 'click', () => {
+					@count++;
+				}, { once: true });
+
+				const permanentHandler = on(node, 'click', () => {
+					@permanentCount++;
+				});
+
+				return () => {
+					onceHandler?.();
+					permanentHandler?.();
+				};
+			};
+
+			<button {ref setupListeners}>{'Click me'}</button>
+			<div class="once-count">{@count}</div>
+			<div class="permanent-count">{@permanentCount}</div>
+		}
+
+		render(Basic);
+		flushSync();
+
+		const button = container.querySelector('button');
+		const onceDiv = container.querySelector('.once-count');
+		const permanentDiv = container.querySelector('.permanent-count');
+
+		expect(onceDiv.textContent).toBe('0');
+		expect(permanentDiv.textContent).toBe('0');
+
+		// First click: both handlers should fire
+		button.click();
+		flushSync();
+		expect(onceDiv.textContent).toBe('1');
+		expect(permanentDiv.textContent).toBe('1');
+
+		// Second click: only permanent handler should fire
+		button.click();
+		flushSync();
+		expect(onceDiv.textContent).toBe('1'); // Still 1
+		expect(permanentDiv.textContent).toBe('2');
+
+		// Third click: only permanent handler should fire
+		button.click();
+		flushSync();
+		expect(onceDiv.textContent).toBe('1'); // Still 1
+		expect(permanentDiv.textContent).toBe('3');
+	});
+});

package/tests/client/input-value.test.ripple

@@ -18,6 +18,7 @@ import {
 	bindInnerText,
 	bindTextContent,
 	bindNode,
+	bindFiles,
 } from 'ripple';
 
 // Mock ResizeObserver for testing
@@ -57,9 +58,37 @@ function triggerResize(element: Element, entry: Partial<ResizeObserverEntry>) {
 	}
 }
 
+// Mock DataTransfer for testing file inputs
+class MockDataTransfer {
+	items: MockDataTransferItemList;
+	files: FileList;
+
+	constructor() {
+		this.items = new MockDataTransferItemList();
+		this.files = this.items.files;
+	}
+}
+
+class MockDataTransferItemList {
+	_files: File[] = [];
+
+	get files(): FileList {
+		return this._files as any as FileList;
+	}
+
+	add(file: File): void {
+		this._files.push(file);
+	}
+
+	get length(): number {
+		return this._files.length;
+	}
+}
+
 // Setup ResizeObserver mock
 beforeAll(() => {
 	(global as any).ResizeObserver = createMockResizeObserver;
+	(global as any).DataTransfer = MockDataTransfer;
 });
 
 afterAll(() => {
@@ -1227,6 +1256,265 @@ describe('bindNode', () => {
 	});
 });
 
+describe('bindFiles', () => {
+	it('should bind files from file input', () => {
+		const logs: FileList[] = [];
+
+		component App() {
+			const files = track(null);
+
+			effect(() => {
+				@files;
+				if (@files) logs.push(@files);
+			});
+
+			<input type="file" multiple {ref bindFiles(files)} />
+		}
+
+		render(App);
+		flushSync();
+
+		const input = container.querySelector('input') as HTMLInputElement;
+
+		// Create mock FileList using DataTransfer
+		const dt = new DataTransfer();
+		const file1 = new File(['content1'], 'file1.txt', { type: 'text/plain' });
+		const file2 = new File(['content2'], 'file2.txt', { type: 'text/plain' });
+		dt.items.add(file1);
+		dt.items.add(file2);
+
+		// Simulate file selection
+		Object.defineProperty(input, 'files', {
+			value: dt.files,
+			writable: true,
+		});
+		input.dispatchEvent(new Event('change', { bubbles: true }));
+		flushSync();
+
+		expect(logs.length).toBeGreaterThan(0);
+		const lastFiles = logs[logs.length - 1];
+		expect(lastFiles.length).toBe(2);
+		expect(lastFiles[0].name).toBe('file1.txt');
+		expect(lastFiles[1].name).toBe('file2.txt');
+	});
+
+	it('should update tracked value when files are selected', () => {
+		let capturedFiles: FileList | null = null;
+
+		component App() {
+			const files = track(null);
+
+			effect(() => {
+				capturedFiles = @files;
+			});
+
+			<input type="file" {ref bindFiles(files)} />
+		}
+
+		render(App);
+		flushSync();
+
+		const input = container.querySelector('input') as HTMLInputElement;
+
+		// Create mock file
+		const dt = new DataTransfer();
+		const file = new File(['test content'], 'test.txt', { type: 'text/plain' });
+		dt.items.add(file);
+
+		Object.defineProperty(input, 'files', {
+			value: dt.files,
+			writable: true,
+		});
+		input.dispatchEvent(new Event('change', { bubbles: true }));
+		flushSync();
+
+		expect(capturedFiles).not.toBeNull();
+		expect(capturedFiles?.length).toBe(1);
+		expect(capturedFiles?.[0].name).toBe('test.txt');
+	});
+
+	it('should allow clearing files via input.files', () => {
+		let capturedFiles: FileList | null = null;
+
+		component App() {
+			const files = track(null);
+			const input = track(null);
+
+			effect(() => {
+				capturedFiles = @files;
+			});
+
+			<div>
+				<input type="file" {ref bindFiles(files)} {ref bindNode(input)} />
+				<button
+					onClick={() => {
+						if (@input) {
+							@input.files = new DataTransfer().files;
+							@input.dispatchEvent(new Event('change', { bubbles: true }));
+						}
+					}}
+				>
+					{'Clear'}
+				</button>
+			</div>
+		}
+
+		render(App);
+		flushSync();
+
+		const input = container.querySelector('input') as HTMLInputElement;
+		const button = container.querySelector('button') as HTMLButtonElement;
+
+		// Add a file first
+		const dt = new DataTransfer();
+		const file = new File(['content'], 'file.txt', { type: 'text/plain' });
+		dt.items.add(file);
+
+		Object.defineProperty(input, 'files', {
+			value: dt.files,
+			writable: true,
+		});
+		input.dispatchEvent(new Event('change', { bubbles: true }));
+		flushSync();
+
+		expect(capturedFiles?.length).toBe(1);
+
+		// Clear via button
+		button.click();
+		flushSync();
+
+		expect(capturedFiles?.length).toBe(0);
+	});
+
+	it('should handle multiple file selections', () => {
+		const fileCounts: number[] = [];
+
+		component App() {
+			const files = track(null);
+
+			effect(() => {
+				@files;
+				if (@files) {
+					fileCounts.push(@files.length);
+				}
+			});
+
+			<input type="file" multiple {ref bindFiles(files)} />
+		}
+
+		render(App);
+		flushSync();
+
+		const input = container.querySelector('input') as HTMLInputElement;
+
+		// First selection: 2 files
+		const dt1 = new DataTransfer();
+		dt1.items.add(new File(['a'], 'a.txt'));
+		dt1.items.add(new File(['b'], 'b.txt'));
+
+		Object.defineProperty(input, 'files', {
+			value: dt1.files,
+			writable: true,
+		});
+		input.dispatchEvent(new Event('change', { bubbles: true }));
+		flushSync();
+
+		// Second selection: 3 files
+		const dt2 = new DataTransfer();
+		dt2.items.add(new File(['x'], 'x.txt'));
+		dt2.items.add(new File(['y'], 'y.txt'));
+		dt2.items.add(new File(['z'], 'z.txt'));
+
+		Object.defineProperty(input, 'files', {
+			value: dt2.files,
+			writable: true,
+		});
+		input.dispatchEvent(new Event('change', { bubbles: true }));
+		flushSync();
+
+		expect(fileCounts).toEqual([2, 3]);
+	});
+
+	it('should handle file input without multiple attribute', () => {
+		let capturedFile: File | null = null;
+
+		component App() {
+			const files = track(null);
+
+			effect(() => {
+				@files;
+				if (@files && @files.length > 0) {
+					capturedFile = @files[0];
+				}
+			});
+
+			<input type="file" {ref bindFiles(files)} />
+		}
+
+		render(App);
+		flushSync();
+
+		const input = container.querySelector('input') as HTMLInputElement;
+
+		const dt = new DataTransfer();
+		const file = new File(['single file content'], 'single.pdf', { type: 'application/pdf' });
+		dt.items.add(file);
+
+		Object.defineProperty(input, 'files', {
+			value: dt.files,
+			writable: true,
+		});
+		input.dispatchEvent(new Event('change', { bubbles: true }));
+		flushSync();
+
+		expect(capturedFile).not.toBeNull();
+		expect(capturedFile?.name).toBe('single.pdf');
+		expect(capturedFile?.type).toBe('application/pdf');
+	});
+
+	it('should handle empty file selection', () => {
+		const logs: (FileList | null)[] = [];
+
+		component App() {
+			const files = track(null);
+
+			effect(() => {
+				logs.push(@files);
+			});
+
+			<input type="file" {ref bindFiles(files)} />
+		}
+
+		render(App);
+		flushSync();
+
+		const input = container.querySelector('input') as HTMLInputElement;
+
+		// Select a file
+		const dt = new DataTransfer();
+		dt.items.add(new File(['test'], 'test.txt'));
+
+		Object.defineProperty(input, 'files', {
+			value: dt.files,
+			writable: true,
+		});
+		input.dispatchEvent(new Event('change', { bubbles: true }));
+		flushSync();
+
+		// Clear selection
+		Object.defineProperty(input, 'files', {
+			value: new DataTransfer().files,
+			writable: true,
+		});
+		input.dispatchEvent(new Event('change', { bubbles: true }));
+		flushSync();
+
+		expect(logs.length).toBeGreaterThan(1);
+		const lastFiles = logs[logs.length - 1];
+		expect(lastFiles?.length).toBe(0);
+	});
+});
+
 describe('error handling', () => {
 	it('should throw error when bindValue receives non-tracked object', () => {
 		expect(() => {
@@ -1371,4 +1659,13 @@ describe('error handling', () => {
 			render(App);
 		}).toThrow('bindNode() argument is not a tracked object');
 	});
+
+	it('should throw error when bindFiles receives non-tracked object', () => {
+		expect(() => {
+			component App() {
+				<input type="file" {ref bindFiles({ value: null })} />
+			}
+			render(App);
+		}).toThrow('bindFiles() argument is not a tracked object');
+	});
 });

package/types/index.d.ts

@@ -307,3 +307,5 @@ export declare function bindOffsetHeight<V>(tracked: Tracked<V>): (node: HTMLEle
 export declare function bindOffsetWidth<V>(tracked: Tracked<V>): (node: HTMLElement) => void;
 
 export declare function bindIndeterminate<V>(tracked: Tracked<V>): (node: HTMLInputElement) => void;
+
+export declare function bindFiles<V>(tracked: Tracked<V>): (node: HTMLInputElement) => void;