ripple 0.2.172 → 0.2.174

package/package.json

@@ -3,7 +3,7 @@
   "description": "Ripple is an elegant TypeScript UI framework",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.2.172",
+  "version": "0.2.174",
   "type": "module",
   "module": "src/runtime/index-client.js",
   "main": "src/runtime/index-client.js",
@@ -78,9 +78,10 @@
   "devDependencies": {
     "@types/estree": "^1.0.8",
     "@types/node": "^24.3.0",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.2",
+    "@volar/language-core": "~2.4.23"
   },
   "peerDependencies": {
-    "ripple": "0.2.172"
+    "ripple": "0.2.174"
   }
 }

package/src/compiler/index.js

@@ -25,20 +25,22 @@ export function parse(source) {
 export function compile(source, filename, options = {}) {
 	const ast = parse_module(source);
 	const analysis = analyze(ast, filename, options);
-	const result = options.mode === 'server'
-		? transform_server(filename, source, analysis)
-		: transform_client(filename, source, analysis, false);
+	const result =
+		options.mode === 'server'
+			? transform_server(filename, source, analysis)
+			: transform_client(filename, source, analysis, false);
 
 	return result;
 }
 
 /** @import { PostProcessingChanges, LineOffsets } from './phases/3-transform/client/index.js' */
+/** @import { MappingsResult } from './phases/3-transform/segments.js' */
 
 /**
  * Compile Ripple component to Volar virtual code with TypeScript mappings
  * @param {string} source
  * @param {string} filename
- * @returns {object} Volar mappings object
+ * @returns {MappingsResult} Volar mappings object
  */
 export function compile_to_volar_mappings(source, filename) {
 	const ast = parse_module(source);
@@ -51,7 +53,7 @@ export function compile_to_volar_mappings(source, filename) {
 		source,
 		transformed.js.code,
 		transformed.js.map,
-    /** @type {PostProcessingChanges} */(transformed.js.post_processing_changes),
-    /** @type {LineOffsets} */(transformed.js.line_offsets)
+		/** @type {PostProcessingChanges} */ (transformed.js.post_processing_changes),
+		/** @type {LineOffsets} */ (transformed.js.line_offsets),
 	);
 }

package/src/compiler/phases/3-transform/segments.js

@@ -1,19 +1,31 @@
+/** @typedef {import('@volar/language-core').CodeMapping} VolarCodeMapping */
+
+/**
+ * @typedef {Object} CustomMappingData
+ * @property {[number]} generatedLengths
+ */
+
+/**
+ * @typedef {VolarCodeMapping & {
+ *   data: VolarCodeMapping['data'] & {
+ *     customData: CustomMappingData
+ *   }
+ * }} CodeMapping
+ */
+
+/** @typedef {{code: string, mappings: CodeMapping[]}} MappingsResult */
+
 import { walk } from 'zimmerframe';
 import { build_source_to_generated_map, get_generated_position } from '../../source-map-utils.js';
 
+/** @type {VolarCodeMapping['data']} */
 export const mapping_data = {
 	verification: true,
 	completion: true,
 	semantic: true,
 	navigation: true,
-	rename: true,
-	codeActions: false, // set to false to disable auto import when importing yourself
-	formatting: false, // not doing formatting through Volar, using Prettier.
-	// these 3 below will be true by default
-	// leaving for reference
-	// hover: true,
-	// definition: true,
-	// references: true,
+	structure: true,
+	format: false,
 };
 
 /**
@@ -28,14 +40,24 @@ export const mapping_data = {
  * @param {object} esrap_source_map - Esrap source map for accurate position lookup
  * @param {PostProcessingChanges } post_processing_changes - Optional post-processing changes
  * @param {number[]} line_offsets - Pre-computed line offsets array for generated code
- * @returns {{ code: string, mappings: Array<{sourceOffsets: number[], generatedOffsets: number[], lengths: number[], data: any}> }}
+ * @returns {MappingsResult}
  */
-export function convert_source_map_to_mappings(ast, source, generated_code, esrap_source_map, post_processing_changes, line_offsets) {
-	/** @type {Array<{sourceOffsets: number[], generatedOffsets: number[], lengths: number[], data: any}>} */
+export function convert_source_map_to_mappings(
+	ast,
+	source,
+	generated_code,
+	esrap_source_map,
+	post_processing_changes,
+	line_offsets,
+) {
+	/** @type {CodeMapping[]} */
 	const mappings = [];
 
-	// Build line offset maps for source and generated code
-	// This allows us to convert line/column positions to byte offsets
+	/**
+	 * Converts line/column positions to byte offsets
+	 * @param {string} text
+	 * @returns {number[]}
+	 */
 	const build_line_offsets = (text) => {
 		const offsets = [0]; // Line 1 starts at offset 0
 		for (let i = 0; i < text.length; i++) {
@@ -73,7 +95,7 @@ export function convert_source_map_to_mappings(ast, source, generated_code, esra
 	const adjusted_source_map = build_source_to_generated_map(
 		esrap_source_map,
 		post_processing_changes,
-		line_offsets
+		line_offsets,
 	);
 
 	// Collect text tokens from AST nodes
@@ -96,11 +118,19 @@ export function convert_source_map_to_mappings(ast, source, generated_code, esra
 				if (node.name && node.loc) {
 					// Check if this identifier has tracked_shorthand metadata (e.g., TrackedMap -> #Map)
 					if (node.metadata?.tracked_shorthand) {
-						tokens.push({ source: node.metadata.tracked_shorthand, generated: node.name, loc: node.loc });
+						tokens.push({
+							source: node.metadata.tracked_shorthand,
+							generated: node.name,
+							loc: node.loc,
+						});
 					} else if (node.metadata?.is_capitalized) {
 						// This identifier was capitalized during transformation
 						// Map the original lowercase name to the capitalized generated name
-						tokens.push({ source: node.metadata.original_name, generated: node.name, loc: node.loc });
+						tokens.push({
+							source: node.metadata.original_name,
+							generated: node.name,
+							loc: node.loc,
+						});
 					} else {
 						// No transformation - source and generated names are the same
 						tokens.push({ source: node.name, generated: node.name, loc: node.loc });
@@ -111,7 +141,11 @@ export function convert_source_map_to_mappings(ast, source, generated_code, esra
 				// JSXIdentifiers can also be capitalized (for dynamic components)
 				if (node.loc && node.name) {
 					if (node.metadata?.is_capitalized) {
-						tokens.push({ source: node.metadata.original_name, generated: node.name, loc: node.loc });
+						tokens.push({
+							source: node.metadata.original_name,
+							generated: node.name,
+							loc: node.loc,
+						});
 					} else {
 						tokens.push({ source: node.name, generated: node.name, loc: node.loc });
 					}
@@ -130,7 +164,7 @@ export function convert_source_map_to_mappings(ast, source, generated_code, esra
 						source: '',
 						generated: '',
 						loc: node.loc,
-						is_import_statement: true
+						is_import_statement: true,
 					});
 				}
 
@@ -152,7 +186,10 @@ export function convert_source_map_to_mappings(ast, source, generated_code, esra
 					visit(node.local);
 				}
 				return;
-			} else if (node.type === 'ImportDefaultSpecifier' || node.type === 'ImportNamespaceSpecifier') {
+			} else if (
+				node.type === 'ImportDefaultSpecifier' ||
+				node.type === 'ImportNamespaceSpecifier'
+			) {
 				// Just visit local
 				if (node.local) {
 					visit(node.local);
@@ -246,17 +283,32 @@ export function convert_source_map_to_mappings(ast, source, generated_code, esra
 				}
 
 				// 3. Push closing tag name (not visited by AST walker)
-				if (!node.openingElement?.selfClosing && node.closingElement?.name?.type === 'JSXIdentifier') {
+				if (
+					!node.openingElement?.selfClosing &&
+					node.closingElement?.name?.type === 'JSXIdentifier'
+				) {
 					const closingNameNode = node.closingElement.name;
 					if (closingNameNode.metadata?.is_capitalized) {
-						tokens.push({ source: closingNameNode.metadata.original_name, generated: closingNameNode.name, loc: closingNameNode.loc });
+						tokens.push({
+							source: closingNameNode.metadata.original_name,
+							generated: closingNameNode.name,
+							loc: closingNameNode.loc,
+						});
 					} else {
-						tokens.push({ source: closingNameNode.name, generated: closingNameNode.name, loc: closingNameNode.loc });
+						tokens.push({
+							source: closingNameNode.name,
+							generated: closingNameNode.name,
+							loc: closingNameNode.loc,
+						});
 					}
 				}
 
 				return;
-			} else if (node.type === 'FunctionDeclaration' || node.type === 'FunctionExpression' || node.type === 'ArrowFunctionExpression') {
+			} else if (
+				node.type === 'FunctionDeclaration' ||
+				node.type === 'FunctionExpression' ||
+				node.type === 'ArrowFunctionExpression'
+			) {
 				// Add function/component keyword token
 				if (node.type === 'FunctionDeclaration' || node.type === 'FunctionExpression') {
 					const source_keyword = node.metadata?.was_component ? 'component' : 'function';
@@ -266,8 +318,11 @@ export function convert_source_map_to_mappings(ast, source, generated_code, esra
 						generated: 'function',
 						loc: {
 							start: { line: node.loc.start.line, column: node.loc.start.column },
-							end: { line: node.loc.start.line, column: node.loc.start.column + source_keyword.length }
-						}
+							end: {
+								line: node.loc.start.line,
+								column: node.loc.start.column + source_keyword.length,
+							},
+						},
 					});
 				}
 
@@ -654,7 +709,11 @@ export function convert_source_map_to_mappings(ast, source, generated_code, esra
 					}
 				}
 				return;
-			} else if (node.type === 'JSXClosingElement' || node.type === 'JSXClosingFragment' || node.type === 'JSXOpeningFragment') {
+			} else if (
+				node.type === 'JSXClosingElement' ||
+				node.type === 'JSXClosingFragment' ||
+				node.type === 'JSXOpeningFragment'
+			) {
 				// These are handled by their parent nodes
 				return;
 			} else if (node.type === 'JSXMemberExpression') {
@@ -736,7 +795,10 @@ export function convert_source_map_to_mappings(ast, source, generated_code, esra
 				}
 				// Skip typeAnnotation
 				return;
-			} else if (node.type === 'TSTypeParameterInstantiation' || node.type === 'TSTypeParameterDeclaration') {
+			} else if (
+				node.type === 'TSTypeParameterInstantiation' ||
+				node.type === 'TSTypeParameterDeclaration'
+			) {
 				// Generic type parameters - visit to collect type variable names
 				if (node.params) {
 					for (const param of node.params) {
@@ -881,7 +943,10 @@ export function convert_source_map_to_mappings(ast, source, generated_code, esra
 					visit(node.typeAnnotation);
 				}
 				return;
-			} else if (node.type === 'TSCallSignatureDeclaration' || node.type === 'TSConstructSignatureDeclaration') {
+			} else if (
+				node.type === 'TSCallSignatureDeclaration' ||
+				node.type === 'TSConstructSignatureDeclaration'
+			) {
 				// Call or construct signature
 				if (node.typeParameters) {
 					visit(node.typeParameters);
@@ -1078,7 +1143,22 @@ export function convert_source_map_to_mappings(ast, source, generated_code, esra
 					visit(node.typeAnnotation);
 				}
 				return;
-			} else if (node.type === 'TSAnyKeyword' || node.type === 'TSUnknownKeyword' || node.type === 'TSNumberKeyword' || node.type === 'TSObjectKeyword' || node.type === 'TSBooleanKeyword' || node.type === 'TSBigIntKeyword' || node.type === 'TSStringKeyword' || node.type === 'TSSymbolKeyword' || node.type === 'TSVoidKeyword' || node.type === 'TSUndefinedKeyword' || node.type === 'TSNullKeyword' || node.type === 'TSNeverKeyword' || node.type === 'TSThisType' || node.type === 'TSIntrinsicKeyword') {
+			} else if (
+				node.type === 'TSAnyKeyword' ||
+				node.type === 'TSUnknownKeyword' ||
+				node.type === 'TSNumberKeyword' ||
+				node.type === 'TSObjectKeyword' ||
+				node.type === 'TSBooleanKeyword' ||
+				node.type === 'TSBigIntKeyword' ||
+				node.type === 'TSStringKeyword' ||
+				node.type === 'TSSymbolKeyword' ||
+				node.type === 'TSVoidKeyword' ||
+				node.type === 'TSUndefinedKeyword' ||
+				node.type === 'TSNullKeyword' ||
+				node.type === 'TSNeverKeyword' ||
+				node.type === 'TSThisType' ||
+				node.type === 'TSIntrinsicKeyword'
+			) {
 				// Primitive type keywords - leaf nodes, no children
 				return;
 			} else if (node.type === 'TSDeclareFunction') {
@@ -1120,23 +1200,40 @@ export function convert_source_map_to_mappings(ast, source, generated_code, esra
 			}
 
 			throw new Error(`Unhandled AST node type in mapping walker: ${node.type}`);
-		}
+		},
 	});
 
 	// Process each token in order
 	// All tokens now have .loc property - no need for fallback logic
 	for (const token of tokens) {
 		const source_text = token.source;
+		const gen_text = token.generated;
 
 		// Handle import statement full-statement mapping
 		if (token.is_import_statement) {
 			// Get source position from start
-			const source_start = loc_to_offset(token.loc.start.line, token.loc.start.column, source_line_offsets);
-			const source_end = loc_to_offset(token.loc.end.line, token.loc.end.column, source_line_offsets);
+			const source_start = loc_to_offset(
+				token.loc.start.line,
+				token.loc.start.column,
+				source_line_offsets,
+			);
+			const source_end = loc_to_offset(
+				token.loc.end.line,
+				token.loc.end.column,
+				source_line_offsets,
+			);
 
 			// Get generated positions using source map
-			const gen_start_pos = get_generated_position(token.loc.start.line, token.loc.start.column, adjusted_source_map);
-			const gen_end_pos = get_generated_position(token.loc.end.line, token.loc.end.column, adjusted_source_map);
+			const gen_start_pos = get_generated_position(
+				token.loc.start.line,
+				token.loc.start.column,
+				adjusted_source_map,
+			);
+			const gen_end_pos = get_generated_position(
+				token.loc.end.line,
+				token.loc.end.column,
+				adjusted_source_map,
+			);
 
 			if (source_start !== null && source_end !== null && gen_start_pos && gen_end_pos) {
 				// Convert generated line:col to byte offsets
@@ -1152,7 +1249,11 @@ export function convert_source_map_to_mappings(ast, source, generated_code, esra
 					lengths: [Math.min(source_length, gen_length)],
 					data: {
 						// only verification (diagnostics) to avoid duplicate hover/completion
-						verification: true
+						verification: true,
+
+						customData: {
+							generatedLengths: [gen_text.length],
+						},
 					},
 				});
 			}
@@ -1160,25 +1261,42 @@ export function convert_source_map_to_mappings(ast, source, generated_code, esra
 		}
 
 		// Use .loc to get the exact source position
-		const source_pos = loc_to_offset(token.loc.start.line, token.loc.start.column, source_line_offsets);
+		const source_pos = loc_to_offset(
+			token.loc.start.line,
+			token.loc.start.column,
+			source_line_offsets,
+		);
 
 		// Get generated position using source map
-		const gen_line_col = get_generated_position(token.loc.start.line, token.loc.start.column, adjusted_source_map);
+		const gen_line_col = get_generated_position(
+			token.loc.start.line,
+			token.loc.start.column,
+			adjusted_source_map,
+		);
 		let gen_pos = null;
 		if (gen_line_col) {
 			// Convert generated line:col to byte offset
 			gen_pos = gen_loc_to_offset(gen_line_col.line, gen_line_col.column);
 		} else {
 			// No mapping found in source map - this shouldn't happen since all tokens should have mappings
-			console.warn(`[segments.js] No source map entry for token "${source_text}" at ${token.loc.start.line}:${token.loc.start.column}`);
+			console.warn(
+				`[segments.js] No source map entry for token "${source_text}" at ${token.loc.start.line}:${token.loc.start.column}`,
+			);
 		}
 
 		if (source_pos !== null && gen_pos !== null) {
+			// !IMPORTANT: don't set generatedLengths, otherwise Volar will use that vs our source
+			// We're adding it to our custom metadata instead as we need it for patching positions
 			mappings.push({
 				sourceOffsets: [source_pos],
 				generatedOffsets: [gen_pos],
 				lengths: [source_text.length],
-				data: mapping_data,
+				data: {
+					...mapping_data,
+					customData: {
+						generatedLengths: [gen_text.length],
+					},
+				},
 			});
 		}
 	}
@@ -1195,9 +1313,10 @@ export function convert_source_map_to_mappings(ast, source, generated_code, esra
 			lengths: [1],
 			data: {
 				...mapping_data,
-				codeActions: true, // auto-import
-				rename: false, // avoid rename for a “dummy” mapping
-			}
+				customData: {
+					generatedLengths: [1],
+				},
+			},
 		});
 	}
 

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

@@ -256,10 +256,10 @@ export function bindChecked(maybe_tracked) {
 		throw not_tracked_type_error('bindChecked()');
 	}
 
-	const tracked = /** @type {Tracked} */ (maybe_tracked);
+	var tracked = /** @type {Tracked} */ (maybe_tracked);
 
 	return (input) => {
-		const clear_event = on(input, 'change', () => {
+		var clear_event = on(input, 'change', () => {
 			set(tracked, input.checked);
 		});
 
@@ -281,10 +281,10 @@ export function bindIndeterminate(maybe_tracked) {
 		throw not_tracked_type_error('bindIndeterminate()');
 	}
 
-	const tracked = /** @type {Tracked} */ (maybe_tracked);
+	var tracked = /** @type {Tracked} */ (maybe_tracked);
 
 	return (input) => {
-		const clear_event = on(input, 'change', () => {
+		var clear_event = on(input, 'change', () => {
 			set(tracked, input.indeterminate);
 		});
 
@@ -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;
 			}
 		});
 
@@ -373,7 +367,7 @@ function bind_element_size(maybe_tracked, type) {
 		);
 
 		effect(() => {
-			untrack(() => set(tracked, element[type]));
+			set(tracked, element[type]);
 			return unsubscribe;
 		});
 	};
@@ -480,10 +474,10 @@ export function bind_content_editable(maybe_tracked, property) {
 		throw not_tracked_type_error(`bind${property.charAt(0).toUpperCase() + property.slice(1)}()`);
 	}
 
-	const tracked = /** @type {Tracked} */ (maybe_tracked);
+	var tracked = /** @type {Tracked} */ (maybe_tracked);
 
 	return (element) => {
-		const clear_event = on(element, 'input', () => {
+		var clear_event = on(element, 'input', () => {
 			set(tracked, element[property]);
 		});
 
@@ -530,6 +524,34 @@ 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()');
+	}
+
+	var tracked = /** @type {Tracked} */ (maybe_tracked);
+
+	return (input) => {
+		var clear_event = on(input, 'change', () => {
+			set(tracked, input.files);
+		});
+
+		effect(() => {
+			var value = get(tracked);
+
+			if (value !== input.files && value instanceof FileList) {
+				input.files = value;
+			}
+		});
+
+		return clear_event;
+	};
+}
+
 /**
  * Syntactic sugar for binding a HTMLElement with {ref fn}
  * @param {unknown} maybe_tracked
@@ -540,7 +562,7 @@ export function bindNode(maybe_tracked) {
 		throw not_tracked_type_error('bindNode()');
 	}
 
-	const tracked = /** @type {Tracked} */ (maybe_tracked);
+	var tracked = /** @type {Tracked} */ (maybe_tracked);
 
 	/** @param {HTMLElement} node */
 	return (node) => {

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

@@ -369,8 +369,10 @@ export function destroy_block(block, remove_dom = true) {
 
 	if ((remove_dom && (f & (BRANCH_BLOCK | ROOT_BLOCK)) !== 0) || (f & HEAD_BLOCK) !== 0) {
 		var s = block.s;
-		remove_block_dom(s.start, s.end);
-		removed = true;
+		if (s !== null) {
+			remove_block_dom(s.start, s.end);
+			removed = true;
+		}
 	}
 
 	destroy_block_children(block, remove_dom && !removed);

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/basic/basic.components.test.ripple

@@ -284,4 +284,29 @@ describe('basic client > components & composition', () => {
 			render(App);
 		}).not.toThrow();
 	});
+
+	it('handles component without any output', () => {
+		component Noop() {
+			// No output
+		}
+
+		component Op() {
+			<div>{'Some HTML content'}</div>
+		}
+
+		component App() {
+			let Content = track(() => Noop);
+			<@Content />
+
+			<button onClick={() => @Content = Op}>{'Show Op'}</button>
+		}
+
+		render(App);
+
+		const button = container.querySelector('button');
+
+		expect(() => {
+			button.click();
+		}).not.toThrow();
+	});
 });

package/tests/client/composite/composite.props.test.ripple

@@ -81,7 +81,7 @@ describe('composite > props', () => {
 				logs.push(@count);
 			});
 
-			<button onClick={() => @count = @count + 1}>{'+'}</button>
+			<button onClick={() => (@count = @count + 1)}>{'+'}</button>
 		}
 
 		component App() {
@@ -122,7 +122,7 @@ describe('composite > props', () => {
 
 		component Toggle(props) {
 			const [pressed, rest] = trackSplit(props, ['pressed']);
-			const onClick = () => @pressed = !@pressed;
+			const onClick = () => (@pressed = !@pressed);
 			<Button {...@rest} class={@pressed ? 'on' : 'off'} {onClick}>{'button 1'}</Button>
 			<Button class={@pressed ? 'on' : 'off'} {onClick}>{'button 2'}</Button>
 		}

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;