Add useModel to use a model in a component

## Summary

Add `useModel` hook to `@preact/signals` and `@preact/signals-react` packages for using Models (created with `createModel`) within components.

The hook handles:
- Creating the model instance lazily on first render
- Maintaining the same instance across re-renders
- Automatically disposing the model when the component unmounts

## Usage

```jsx
import { createModel, signal } from "@preact/signals-core";
import { useModel } from "@preact/signals"; // or "@preact/signals-react"

const CountModel = createModel(() => ({
  count: signal(0),
  increment() {
    this.count.value++;
  },
}));

function Counter() {
  const model = useModel(CountModel);
  return <button onClick={() => model.increment()}>{model.count}</button>;
}
```

For models that require constructor arguments, wrap in a factory function:

```jsx
const CountModel = createModel((initialCount: number) => ({
  count: signal(initialCount),
}));

function Counter() {
  const model = useModel(() => new CountModel(5));
  return <div>{model.count}</div>;
}
```

## Changes

- Added `useModel` hook to `@preact/signals` (`packages/preact/src/index.ts`)
- Added `useModel` hook to `@preact/signals-react` (`packages/react/runtime/src/index.ts`)
- Added comprehensive tests for both implementations
- Updated todo demo to use the new hook instead of a local implementation

## Test plan

- [x] Unit tests for Preact implementation (`packages/preact/test/browser/useModel.test.tsx`)
- [x] Unit tests for React implementation (`packages/react/runtime/test/browser/useModel.test.tsx`)
- [x] Run `pnpm test` to verify all tests pass
- [x] Verify todo demo works correctly with the new hook

Author: andrewiggins

.changeset/brave-frogs-trade.md

@@ -0,0 +1,42 @@
+---
+"@preact/signals": minor
+"@preact/signals-react": minor
+---
+
+Add `useModel` hook for using Models in components
+
+The new `useModel` hook provides a convenient way to use Models (created with `createModel`) within React and Preact components. It handles:
+
+- Creating the model instance lazily on first render
+- Maintaining the same instance across re-renders
+- Automatically disposing the model when the component unmounts
+
+```jsx
+import { createModel, signal } from "@preact/signals-core";
+import { useModel } from "@preact/signals-react"; // or "@preact/signals"
+
+const CountModel = createModel(() => ({
+	count: signal(0),
+	increment() {
+		this.count.value++;
+	},
+}));
+
+function Counter() {
+	const model = useModel(CountModel);
+	return <button onClick={() => model.increment()}>{model.count}</button>;
+}
+```
+
+For models that require constructor arguments, wrap in a factory function:
+
+```jsx
+const CountModel = createModel((initialCount: number) => ({
+  count: signal(initialCount),
+}));
+
+function Counter() {
+  const model = useModel(() => new CountModel(5));
+  return <div>{model.count}</div>;
+}
+```

docs/demos/todo/index.tsx

@@ -1,4 +1,3 @@
-import { useEffect, useState } from "preact/hooks";
 import {
 	createModel,
 	signal,
@@ -7,7 +6,8 @@ import {
 	Model,
 	ModelConstructor,
 	ReadonlySignal,
-} from "@preact/signals-core";
+	useModel,
+} from "@preact/signals";
 import { For, Show } from "@preact/signals/utils";
 import "./style.css";
 
@@ -92,6 +92,7 @@ interface TodosViewModel {
 	filter: ReadonlySignal<"all" | "active" | "completed">;
 	filteredTodos: ReadonlySignal<Todo[]>;
 	setFilter: (newFilter: "all" | "active" | "completed") => void;
+	debugData: ReadonlySignal<string>;
 }
 
 // View model - manages UI state and filtering, composes the business model
@@ -151,12 +152,6 @@ const TodosViewModel: ModelConstructor<TodosViewModel> = createModel(() => {
 	};
 });
 
-function useModel<TModel>(constructModel: () => Model<TModel>): Model<TModel> {
-	const model = useState(() => constructModel())[0];
-	useEffect(() => () => model[Symbol.dispose]());
-	return model;
-}
-
 function FilterButton({
 	filterType,
 	currentFilter,

package.json

@@ -84,8 +84,8 @@
     "prettier": "^3.6.2",
     "shx": "^0.3.4",
     "typescript": "~5.8.3",
-    "vitest": "^4.0.17",
-    "vite": "^6.3.5"
+    "vite": "^6.3.5",
+    "vitest": "^4.0.17"
   },
   "lint-staged": {
     "**/*.{js,mjs,jsx,ts,tsx,yml,yaml,json,md,html,css}": [

packages/core/src/index.ts

@@ -971,6 +971,9 @@ export type ModelConstructor<TModel, TFactoryArgs extends any[] = []> = new (
  * this internal interface that extends the public interface but also
  * allows calling without `new`.
  *
+ * This pattern is used by the Preact & React adapters to make instantiating
+ * a model or a function that returns a model easier.
+ *
  * @internal
  */
 interface InternalModelConstructor<TModel, TFactoryArgs extends any[]>

packages/preact/src/index.ts

@@ -491,6 +491,24 @@ export function useSignalEffect(
 	}, []);
 }
 
+/** See comment in packages/core/src/index.ts on the same interface for an explanation */
+interface InternalModelConstructor<TModel, TArgs extends any[]>
+	extends ModelConstructor<TModel, TArgs> {
+	(...args: TArgs): Model<TModel>;
+}
+
+export function useModel<TModel>(
+	factory: ModelConstructor<TModel, []> | (() => Model<TModel>)
+): Model<TModel> {
+	type InternalFactory =
+		| InternalModelConstructor<TModel, []>
+		| (() => Model<TModel>);
+
+	const [inst] = useState(() => (factory as InternalFactory)());
+	useEffect(() => inst[Symbol.dispose], [inst]);
+	return inst;
+}
+
 /**
  * @todo Determine which Reactive implementation we'll be using.
  * @internal

packages/preact/test/browser/useModel.test.tsx

@@ -0,0 +1,231 @@
+import { createModel, signal, useModel } from "@preact/signals";
+import { createElement, render, Fragment } from "preact";
+import { act } from "preact/test-utils";
+import {
+	describe,
+	it,
+	expect,
+	MockInstance,
+	vi,
+	beforeEach,
+	afterEach,
+} from "vitest";
+
+describe("useModel", () => {
+	let scratch: HTMLDivElement;
+
+	beforeEach(() => {
+		scratch = document.createElement("div");
+	});
+
+	afterEach(() => {
+		render(null, scratch);
+	});
+
+	it("creates model instance using model constructor", () => {
+		const CountModel = createModel(() => ({
+			count: signal(0),
+			increment() {
+				this.count.value++;
+			},
+		}));
+
+		function Counter() {
+			const model = useModel(CountModel);
+			return <button onClick={() => model.increment()}>{model.count}</button>;
+		}
+
+		render(<Counter />, scratch);
+		const button = scratch.querySelector("button")!;
+
+		expect(button.textContent).toBe("0");
+
+		act(() => button.click());
+
+		expect(button.textContent).toBe("1");
+	});
+
+	it("creates model instance using wrapper around model constructor", () => {
+		const CountModel = createModel(() => ({
+			count: signal(0),
+			increment() {
+				this.count.value++;
+			},
+		}));
+
+		function Counter() {
+			const model = useModel(() => new CountModel());
+			return <button onClick={() => model.increment()}>{model.count}</button>;
+		}
+
+		render(<Counter />, scratch);
+		const button = scratch.querySelector("button")!;
+
+		expect(button.textContent).toBe("0");
+
+		act(() => button.click());
+
+		expect(button.textContent).toBe("1");
+	});
+
+	it("creates model instance using wrapper around model constructor with arguments", () => {
+		const CountModel = createModel((initialCount: number) => ({
+			count: signal(initialCount),
+			increment() {
+				this.count.value++;
+			},
+		}));
+
+		function Counter() {
+			const model = useModel(() => new CountModel(5));
+			return <button onClick={() => model.increment()}>{model.count}</button>;
+		}
+
+		render(<Counter />, scratch);
+		const button = scratch.querySelector("button")!;
+
+		expect(button.textContent).toBe("5");
+
+		act(() => button.click());
+
+		expect(button.textContent).toBe("6");
+	});
+
+	it("returns the same instance across multiple renders", () => {
+		const CountModel = createModel(() => ({
+			count: signal(0),
+			increment() {
+				this.count.value++;
+			},
+		}));
+
+		let modelInstances: any[] = [];
+
+		function Counter() {
+			const model = useModel(() => new CountModel());
+			modelInstances.push(model);
+			return (
+				<button onClick={() => model.increment()}>{model.count.value}</button>
+			);
+		}
+
+		render(<Counter />, scratch);
+		const button = scratch.querySelector("button")!;
+
+		expect(button.textContent).toBe("0");
+		expect(modelInstances.length).toBe(1);
+
+		act(() => button.click());
+
+		expect(button.textContent).toBe("1");
+		expect(modelInstances.length).toBe(2);
+		expect(modelInstances[0]).toBe(modelInstances[1]);
+	});
+
+	it("diposes the model on unmount", () => {
+		const CountModel = createModel(() => ({ count: signal(0) }));
+
+		let disposeSpy: MockInstance | undefined;
+		function Counter() {
+			const model = useModel(CountModel);
+			disposeSpy = vi.spyOn(model, Symbol.dispose);
+			return <div>{model.count}</div>;
+		}
+
+		act(() => render(<Counter />, scratch));
+		expect(disposeSpy).not.toHaveBeenCalled();
+
+		act(() => render(null, scratch));
+		expect(disposeSpy).toHaveBeenCalledTimes(1);
+	});
+
+	it("disposes the model on unmount when created via a factory function", () => {
+		const CountModel = createModel(() => ({ count: signal(0) }));
+
+		let disposeSpy: MockInstance | undefined;
+		function Counter() {
+			const model = useModel(() => new CountModel());
+			disposeSpy = vi.spyOn(model, Symbol.dispose);
+			return <div>{model.count}</div>;
+		}
+
+		act(() => render(<Counter />, scratch));
+		expect(disposeSpy).not.toHaveBeenCalled();
+
+		act(() => render(null, scratch));
+		expect(disposeSpy).toHaveBeenCalledTimes(1);
+	});
+
+	it("ignores changing the factory function between renders", () => {
+		const CountModel = createModel(() => ({
+			count: signal(0),
+			increment() {
+				this.count.value++;
+			},
+		}));
+
+		let modelInstances: any[] = [];
+		let useAlternateFactory = false;
+
+		function Counter() {
+			const factory = useAlternateFactory ? () => new CountModel() : CountModel;
+			const model = useModel(factory);
+			modelInstances.push(model);
+			return (
+				<button onClick={() => model.increment()}>{model.count.value}</button>
+			);
+		}
+
+		render(<Counter />, scratch);
+		const button = scratch.querySelector("button")!;
+
+		expect(button.textContent).toBe("0");
+		expect(modelInstances.length).toBe(1);
+
+		act(() => {
+			useAlternateFactory = true;
+			button.click();
+		});
+
+		expect(button.textContent).toBe("1");
+		expect(modelInstances.length).toBe(2);
+		expect(modelInstances[0]).toBe(modelInstances[1]);
+	});
+
+	describe("Typescript Types", () => {
+		it("fail when using useModel with incompatible model constructor", () => {
+			function SimpleClass() {
+				// @ts-expect-error Should be a ModelConstructor
+				expect(() => useModel(class {})).toThrow();
+				return null;
+			}
+
+			function SimpleFunction() {
+				// @ts-expect-error Factory should return a Model Constructor
+				useModel(() => ({}));
+				return null;
+			}
+
+			const ModelWithArgs = createModel((arg: number) => ({
+				value: signal(arg),
+			}));
+
+			function WithArgs() {
+				// @ts-expect-error useModel cannot instantiate a model constructor with arguments
+				useModel(ModelWithArgs);
+				// Correct usage is to wrap in a factory function
+				useModel(() => new ModelWithArgs(0));
+				return null;
+			}
+
+			render(
+				<>
+					<SimpleClass />
+					<SimpleFunction />
+					<WithArgs />
+				</>,
+				scratch
+			);
+		});
+	});
+});

packages/react/runtime/src/index.ts

@@ -6,8 +6,11 @@ import {
 	ReadonlySignal,
 	SignalOptions,
 	EffectOptions,
+	type Model,
+	type ModelConstructor,
 } from "@preact/signals-core";
 import {
+	useState,
 	useRef,
 	useMemo,
 	useEffect,
@@ -441,3 +444,21 @@ declare global {
 		__PREACT_SIGNALS_DEVTOOLS__: SignalsDevToolsAPI;
 	}
 }
+
+/** See comment in packages/core/src/index.ts on the same interface for an explanation */
+interface InternalModelConstructor<TModel, TArgs extends any[]>
+	extends ModelConstructor<TModel, TArgs> {
+	(...args: TArgs): Model<TModel>;
+}
+
+export function useModel<TModel>(
+	factory: ModelConstructor<TModel, []> | (() => Model<TModel>)
+): Model<TModel> {
+	type InternalFactory =
+		| InternalModelConstructor<TModel, []>
+		| (() => Model<TModel>);
+
+	const [inst] = useState(() => (factory as InternalFactory)());
+	useEffect(() => inst[Symbol.dispose], [inst]);
+	return inst;
+}