Add createModel API for reactive state containers (#812)

## Summary

This PR adds `createModel` and `action` to `@preact/signals-core`, providing a structured way to build reactive state containers that encapsulate signals, computed values, effects, and actions.

```js
const CounterModel = createModel((initialCount = 0) => {
	const count = signal(initialCount);
	const doubled = computed(() => count.value * 2);

	effect(() => {
		console.log("Count changed:", count.value);
	});

	return {
		count,
		doubled,
		increment() {
			count.value++;
		},
	};
});

const counter = new CounterModel(5);
counter.increment(); // Updates are automatically batched
counter[Symbol.dispose](); // Cleans up all effects
```

Key features:

- Factory functions can accept arguments for initialization
- All methods are automatically wrapped as actions (batched & untracked)
- Effects created during model construction are captured and disposed when the model is disposed via `Symbol.dispose`
- Models compose naturally - effects from nested models are captured by the parent and disposed together when the parent is disposed
- TypeScript validates that models only contain signals, actions, or nested objects with signals/actions

## Design decisions

### No classes or reflection

The implementation avoids using ES classes internally. Using a class would require reflecting onto a class's constructor and the current signals implementation avoids reflection and proxies, so this follows a similar design philosophy. A class-based API could be built on top of this primitive, like so (shoutout @developit for this neat little hack):

```ts
class BaseModelImpl implements Disposable {
	[Symbol.dispose](): void {}
}

export const BaseModel = new Proxy(BaseModelImpl, {
	construct(target, args, newTarget) {
		return createModel(() => Reflect.construct(target, args, newTarget));
	},
}) as unknown as typeof BaseModelImpl;
```

### Using `new` to instantiate models

The public types require using `new` to instantiate models. This helps disambiguate the factory function passed into `createModel` from the returned constructor. It's easier to explain that "`createModel` accepts a factory and returns a class" than "`createModel` accepts a factory and returns a factory."

In other words, this:

```ts
const PersonModel = createModel((name: string) => ({ ... }));
const person = new PersonModel("John");
```

is easier to understand than:

```ts
const createPerson = createModel((name: string) => ({ ... }));
const person = createPerson("John");
```

Using `new` also communicates that each call creates a fresh instance with independent state.

Internally, `createModel` returns a plain function that can be called without `new` for simplicity, but the public types enforce `new` for clarity.

### Automatically capture effects implement a dispose function

Effects declared inside a model's factory function are captured by `createModel` in order to automatically implement a dispose function on the model (exposed as `[Symbol.dispose]`). This design avoids models needing to manually wire up effect dispose from nested models to the model interface.

### Factory functions should NOT return `dispose` functions

If a model needs to run custom logic when it is diposed (that may not be related to signals), it should **not** return a `dispose()` or `[Symbol.dispose]`. When composing models, this dispose function isn't guarenteed to get called as parent models would need to know that your model has a dispose and manually wire it up.

Instead for custom cleanup logic, the recommended pattern is to declare an effect with no signal dependencies that returns a cleanup function that runs the desired cleanup logic. (see "Dispose pattern" below).

## Recommended patterns

### Explicit readonly pattern

Declare your model interface explicitly and use `ReadonlySignal` for signals that should only be modified through actions. This ensures only actions can modify signals, giving you better insight and control over state changes:

```ts
import {
	signal,
	computed,
	createModel,
	ReadonlySignal,
} from "@preact/signals-core";

interface Counter {
	count: ReadonlySignal<number>;
	doubled: ReadonlySignal<number>;
	increment(): void;
	decrement(): void;
}

const CounterModel = createModel<Counter>(() => {
	const count = signal(0);
	const doubled = computed(() => count.value * 2);

	return {
		count,
		doubled,
		increment() {
			count.value++;
		},
		decrement() {
			count.value--;
		},
	};
});

const counter = new CounterModel();
counter.increment(); // OK
counter.count.value = 10; // TypeScript error: Cannot assign to 'value' because it is a read-only property
```

### Dispose pattern

Generally, if you delcare an effect that has cleanup logic, that cleanup logic will before each execution of the effect function (aka whenever the signals your effect relies on update).

However, if you have cleanup logic that needs to run on model dispose that doesn't depend on signals, define an effect that uses no signals but returns your cleanup function. This mirrors the `useEffect(() => { return cleanup }, [])` pattern in React:

```ts
const WebSocketModel = createModel((url: string) => {
	const messages = signal<string[]>([]);
	const ws = new WebSocket(url);

	ws.onmessage = e => {
		messages.value = [...messages.value, e.data];
	};

	// This effect runs once and cleanup is called on dispose
	effect(() => {
		return () => {
			ws.close();
		};
	});

	return {
		messages,
		send(message: string) {
			ws.send(message);
		},
	};
});
```

This pattern is recommended for custom dispose behavior because it allows models to compose naturally - nested models will have their effects cleaned up automatically without manually wiring up dispose functions.

## Future work

- Add `useModel` hook to Preact & React adapters
- Extend debug transform to add names to models & actions, and use model name in signals, computeds, effects, and actions declared within the model
- Extend debug tooling to understand models and actions

Author: andrewiggins

.changeset/hungry-apricots-shake.md

@@ -0,0 +1,45 @@
+---
+"@preact/signals-core": minor
+---
+
+Add `createModel` and `action` to signals core package
+
+**`createModel`** provides a structured way to create reactive model classes that encapsulate signals, computed values, and actions:
+
+```js
+const CounterModel = createModel((initialCount = 0) => {
+	const count = signal(initialCount);
+	const doubled = computed(() => count.value * 2);
+
+	effect(() => {
+		console.log("Count changed:", count.value);
+	});
+
+	return {
+		count,
+		doubled,
+		increment() {
+			count.value++;
+		},
+	};
+});
+
+const counter = new CounterModel(5);
+counter.increment(); // Updates are automatically batched
+counter[Symbol.dispose](); // Cleans up all effects
+```
+
+Key features:
+
+- Factory functions can accept arguments for initialization
+- All methods are automatically wrapped as actions (batched & untracked)
+- Effects created during model construction are captured and disposed when the model is disposed via `Symbol.dispose`
+- TypeScript validates that models only contain signals, actions, or nested objects with signals/actions
+
+**`action`** is a helper that wraps a function to run batched and untracked:
+
+```js
+const updateAll = action(items => {
+	items.forEach(item => item.value++);
+}); // All updates batched into single notification
+```

docs/demos/index.tsx

@@ -13,6 +13,7 @@ const demos = {
 	Sum,
 	GlobalCounter,
 	DuelingCounters,
+	Models: lazy(() => import("./todo")),
 	Devtools: lazy(() => import("./devtools")),
 	Nesting: lazy(() => import("./nesting")),
 	Animation: lazy(() => import("./animation")),

docs/demos/render-flasher.tsx

@@ -105,6 +105,9 @@ function hasComponentChild(vnode: VNode): boolean {
 }
 
 function flash(nodes: (Node | undefined)[], annotation?: string) {
+	const scrollX = window.scrollX;
+	const scrollY = window.scrollY;
+
 	const range = new Range();
 	for (let node of nodes) {
 		if (!node) continue;
@@ -123,8 +126,8 @@ function flash(nodes: (Node | undefined)[], annotation?: string) {
 			// styled.style.margin = "-2px";
 			styled.style.background = color;
 			styled.style.boxShadow = `0 0 3px 3px ${color}`;
-			styled.style.left = rect.left + "px";
-			styled.style.top = rect.top + "px";
+			styled.style.left = rect.left + scrollX + "px";
+			styled.style.top = rect.top + scrollY + "px";
 			styled.style.width = rect.width + "px";
 			styled.style.height = rect.height + "px";
 			document.documentElement.appendChild(styled);

docs/demos/todo/index.tsx

@@ -0,0 +1,268 @@
+import { useEffect, useState } from "preact/hooks";
+import {
+	createModel,
+	signal,
+	computed,
+	effect,
+	Model,
+	ModelConstructor,
+	ReadonlySignal,
+} from "@preact/signals-core";
+import { For, Show } from "@preact/signals/utils";
+import "./style.css";
+
+interface Todo {
+	id: number;
+	text: string;
+	completed: boolean;
+}
+
+let nextId = 0;
+
+interface TodosModel {
+	todos: ReadonlySignal<Todo[]>;
+	completedCount: ReadonlySignal<number>;
+	activeCount: ReadonlySignal<number>;
+	addTodo: (text: string) => void;
+	toggleTodo: (id: number) => void;
+	removeTodo: (id: number) => void;
+	clearCompleted: () => void;
+}
+
+// Core business domain model - manages the todo list and operations
+const TodosModel: ModelConstructor<TodosModel> = createModel(() => {
+	const todos = signal<Todo[]>([], { name: "todos" });
+
+	// Computed value: count of completed todos
+	const completedCount = computed(
+		() => todos.value.filter(t => t.completed).length,
+		{ name: "completed-count" }
+	);
+
+	// Computed value: count of active todos
+	const activeCount = computed(
+		() => todos.value.filter(t => !t.completed).length,
+		{ name: "active-count" }
+	);
+
+	// Action: Add a new todo
+	const addTodo = (text: string) => {
+		if (text.trim()) {
+			todos.value = [
+				...todos.value,
+				{
+					id: ++nextId,
+					text: text.trim(),
+					completed: false,
+				},
+			];
+		}
+	};
+
+	// Action: Toggle todo completion status
+	const toggleTodo = (id: number) => {
+		todos.value = todos.value.map(t =>
+			t.id === id ? { ...t, completed: !t.completed } : t
+		);
+	};
+
+	// Action: Remove a todo
+	const removeTodo = (id: number) => {
+		todos.value = todos.value.filter(t => t.id !== id);
+	};
+
+	// Action: Clear all completed todos
+	const clearCompleted = () => {
+		todos.value = todos.value.filter(t => !t.completed);
+	};
+
+	return {
+		todos,
+		completedCount,
+		activeCount,
+		addTodo,
+		toggleTodo,
+		removeTodo,
+		clearCompleted,
+	};
+});
+
+interface TodosViewModel {
+	todosModel: Model<TodosModel>;
+	filter: ReadonlySignal<"all" | "active" | "completed">;
+	filteredTodos: ReadonlySignal<Todo[]>;
+	setFilter: (newFilter: "all" | "active" | "completed") => void;
+}
+
+// View model - manages UI state and filtering, composes the business model
+const TodosViewModel: ModelConstructor<TodosViewModel> = createModel(() => {
+	// Nested model: contains the core business logic
+	const todosModel = new TodosModel();
+
+	// View state: current filter
+	const filter = signal<"all" | "active" | "completed">("all", {
+		name: "filter",
+	});
+
+	// Computed value: filtered todos based on current filter and todos from nested model
+	const filteredTodos = computed(
+		() => {
+			const currentFilter = filter.value;
+			const allTodos = todosModel.todos.value;
+			if (currentFilter === "active") return allTodos.filter(t => !t.completed);
+			if (currentFilter === "completed")
+				return allTodos.filter(t => t.completed);
+			return allTodos;
+		},
+		{ name: "filtered-todos" }
+	);
+
+	// Effect: Update document title with active count (view concern)
+	const originalTitle = document.title;
+	effect(() => {
+		const count = todosModel.activeCount.value;
+		document.title =
+			count === 0 ? "TodoMVC - No active todos" : `TodoMVC (${count} active)`;
+
+		// Cleanup: restore original title when model is disposed
+		return () => {
+			document.title = originalTitle;
+		};
+	});
+
+	// Action: Set the current filter
+	const setFilter = (newFilter: "all" | "active" | "completed") => {
+		filter.value = newFilter;
+	};
+
+	const debugData = computed(() => {
+		return JSON.stringify({todosModel, filter, filteredTodos}, null, 2);
+	});
+
+	return {
+		// Expose the nested business model
+		todosModel,
+		// View-specific state
+		filter,
+		filteredTodos,
+		setFilter,
+		// For debugging purposes in this demo
+		debugData,
+	};
+});
+
+function useModel<TModel>(constructModel: () => Model<TModel>): Model<TModel> {
+	const model = useState(() => constructModel())[0];
+	useEffect(() => () => model[Symbol.dispose]());
+	return model;
+}
+
+function FilterButton({
+	filterType,
+	currentFilter,
+	onClick,
+}: {
+	filterType: "all" | "active" | "completed";
+	currentFilter: ReadonlySignal<"all" | "active" | "completed">;
+	onClick: () => void;
+}) {
+	// Signal reads directly in JSX are reactive - this component only re-renders when currentFilter changes
+	return (
+		<button
+			onClick={onClick}
+			class={`todo-filter-btn ${currentFilter.value === filterType ? "active" : ""}`}
+		>
+			{filterType}
+		</button>
+	);
+}
+
+export default function TodoMVC() {
+	// Create a single instance of the view model that persists across renders
+	const viewModel = useModel(() => new TodosViewModel());
+
+	const handleSubmit = (e: Event) => {
+		e.preventDefault();
+		const form = e.target as HTMLFormElement;
+		const input = form.elements.namedItem("todo-input") as HTMLInputElement;
+		viewModel.todosModel.addTodo(input.value);
+		input.value = "";
+	};
+
+	return (
+		<div class="todo-container">
+			<h1 class="todo-header">TodoMVC Demo</h1>
+			<p class="todo-description">
+				Showcasing <code>createModel</code> with separated business and view
+				models
+			</p>
+
+			{/* Input form */}
+			<form onSubmit={handleSubmit} class="todo-form">
+				<input
+					type="text"
+					name="todo-input"
+					placeholder="What needs to be done?"
+					class="todo-input"
+				/>
+			</form>
+
+			{/* Todo list */}
+			<div class="todo-list">
+				<For each={viewModel.filteredTodos}>
+					{todo => (
+						<div key={todo.id} class="todo-item">
+							<input
+								type="checkbox"
+								checked={todo.completed}
+								onChange={() => viewModel.todosModel.toggleTodo(todo.id)}
+								class="todo-checkbox"
+							/>
+							<span class={`todo-text ${todo.completed ? "completed" : ""}`}>
+								{todo.text}
+							</span>
+							<button
+								onClick={() => viewModel.todosModel.removeTodo(todo.id)}
+								class="todo-delete-btn"
+							>
+								Delete
+							</button>
+						</div>
+					)}
+				</For>
+			</div>
+
+			{/* Footer stats and filters */}
+			<div class="todo-footer">
+				<div class="todo-footer-stats">
+					<div class="todo-stats-text">
+						<strong>{viewModel.todosModel.activeCount}</strong> active,{" "}
+						<strong>{viewModel.todosModel.completedCount}</strong> completed
+					</div>
+					<Show when={viewModel.todosModel.completedCount}>
+						<button
+							onClick={() => viewModel.todosModel.clearCompleted()}
+							class="todo-clear-btn"
+						>
+							Clear completed
+						</button>
+					</Show>
+				</div>
+
+				{/* Filter buttons */}
+				<div class="todo-filters">
+					{(["all", "active", "completed"] as const).map(filterType => (
+						<FilterButton
+							key={filterType}
+							filterType={filterType}
+							currentFilter={viewModel.filter}
+							onClick={() => viewModel.setFilter(filterType)}
+						/>
+					))}
+				</div>
+			</div>
+
+			<pre class="todo-debug">{viewModel.debugData}</pre>
+		</div>
+	);
+}