mvc-kit 2.12.0 → 2.12.1

package/src/react/use-local.ts

@@ -0,0 +1,165 @@
+import { useRef, useEffect } from 'react';
+import type { DependencyList } from 'react';
+import type { Subscribable, Disposable } from '../types';
+import { isSubscribable, isSubscribeOnly, isInitializable } from './guards';
+import { useInstance } from './use-instance';
+import { useSubscribeOnly } from './use-subscribe-only';
+import type { StateOf } from './types';
+
+function depsChanged(prev: DependencyList | undefined, next: DependencyList): boolean {
+  if (prev === undefined) return false;
+  if (prev.length !== next.length) return true;
+  for (let i = 0; i < prev.length; i++) {
+    if (!Object.is(prev[i], next[i])) return true;
+  }
+  return false;
+}
+
+// ── With deps (class + initialState + deps) ────────────────────────
+
+/**
+ * Create component-scoped Subscribable instance, auto-disposed on unmount.
+ * Disposes and recreates when deps change.
+ * Returns [state, instance] tuple.
+ */
+export function useLocal<T extends Subscribable<any> & Disposable>(
+  Class: new (initialState: StateOf<T>) => T,
+  initialState: StateOf<T>,
+  deps: DependencyList,
+): [StateOf<T>, T];
+
+/**
+ * Create component-scoped Subscribable instance via factory, auto-disposed on unmount.
+ * Disposes and recreates when deps change.
+ * Returns [state, instance] tuple.
+ */
+export function useLocal<T extends Subscribable<S> & Disposable, S = StateOf<T>>(
+  factory: () => T,
+  deps: DependencyList,
+): [S, T];
+
+/**
+ * Create component-scoped Disposable instance via factory (non-Subscribable), auto-disposed on unmount.
+ * Disposes and recreates when deps change.
+ * Returns the instance directly.
+ */
+export function useLocal<T extends Disposable>(
+  factory: () => T,
+  deps: DependencyList,
+): T;
+
+// ── Without deps (existing overloads, unchanged) ───────────────────
+
+/**
+ * Create component-scoped Subscribable instance, auto-disposed on unmount.
+ * Returns [state, instance] tuple.
+ */
+export function useLocal<
+  T extends Subscribable<S> & Disposable,
+  S = StateOf<T>,
+  Args extends unknown[] = unknown[]
+>(
+  Class: new (...args: Args) => T,
+  ...args: Args
+): [S, T];
+
+/**
+ * Create component-scoped Disposable instance (non-Subscribable), auto-disposed on unmount.
+ * Returns the instance directly.
+ */
+export function useLocal<T extends Disposable, Args extends unknown[] = unknown[]>(
+  Class: new (...args: Args) => T,
+  ...args: Args
+): T;
+
+/**
+ * Create component-scoped Subscribable instance via factory, auto-disposed on unmount.
+ * Returns [state, instance] tuple.
+ */
+export function useLocal<T extends Subscribable<S> & Disposable, S = StateOf<T>>(
+  factory: () => T
+): [S, T];
+
+/**
+ * Create component-scoped Disposable instance via factory (non-Subscribable), auto-disposed on unmount.
+ * Returns the instance directly.
+ */
+export function useLocal<T extends Disposable>(factory: () => T): T;
+
+// ── Implementation ─────────────────────────────────────────────────
+
+export function useLocal<T extends Disposable, S = StateOf<T>>(
+  classOrFactory: (new (...args: unknown[]) => T) | (() => T),
+  ...rest: unknown[]
+): [S, T] | T {
+  // ── Detect deps: last arg is an array → treat as deps ──
+  let args: unknown[];
+  let deps: DependencyList | undefined;
+
+  if (rest.length > 0 && Array.isArray(rest[rest.length - 1])) {
+    deps = rest[rest.length - 1] as DependencyList;
+    args = rest.slice(0, -1);
+  } else {
+    args = rest;
+    deps = undefined;
+  }
+
+  const instanceRef = useRef<T | null>(null);
+  const mountedRef = useRef(false);
+  const prevDepsRef = useRef<DependencyList | undefined>(undefined);
+
+  // ── Render phase: dep-change detection ──
+  if (deps !== undefined && depsChanged(prevDepsRef.current, deps)) {
+    instanceRef.current?.dispose();
+    instanceRef.current = null;
+  }
+  if (deps !== undefined) {
+    prevDepsRef.current = deps;
+  }
+
+  // ── Create instance if needed ──
+  if (!instanceRef.current || instanceRef.current.disposed) {
+    const isClass =
+      typeof classOrFactory === 'function' &&
+      classOrFactory.prototype &&
+      classOrFactory.prototype.constructor === classOrFactory;
+
+    if (isClass) {
+      instanceRef.current = new (classOrFactory as new (...a: unknown[]) => T)(...args);
+    } else {
+      instanceRef.current = (classOrFactory as () => T)();
+    }
+  }
+
+  // ── Effect: init + deferred cleanup ──
+  useEffect(() => {
+    const instance = instanceRef.current!; // capture for cleanup closure
+    mountedRef.current = true;
+    if (isInitializable(instance)) {
+      instance.init();
+    }
+    return () => {
+      mountedRef.current = false;
+      setTimeout(() => {
+        if (!mountedRef.current) {
+          instance.dispose();
+        }
+      }, 0);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps ?? []);
+
+  // ── Subscribe to state if Subscribable ──
+  if (isSubscribable(instanceRef.current)) {
+    const state = useInstance(instanceRef.current as unknown as Subscribable<S>);
+    return [state, instanceRef.current];
+  }
+
+  // ── Subscribe for re-renders if subscribe-only (e.g., Trackable) ──
+  if (isSubscribeOnly(instanceRef.current)) {
+    useSubscribeOnly(instanceRef.current);
+    return instanceRef.current;
+  }
+
+  return instanceRef.current;
+}

package/src/react/use-model.md

@@ -0,0 +1,364 @@
+# useModel
+
+Bind a [Model](../Model.md) to a React component with automatic lifecycle management. `useModel` creates (or receives) a Model instance, auto-initializes on mount, auto-disposes on unmount, and subscribes to state changes so the component re-renders on every update.
+
+Also exports `useModelRef` (lifecycle-only, no subscription) and `useField` (surgical per-field subscriptions).
+
+---
+
+## Signature
+
+```typescript
+function useModel<M extends Model<any>>(factory: () => M): ModelHandle<StateOf<M>, M>;
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `factory` | `() => M` | Factory that returns a Model instance. Called once on mount (or if the previous instance was disposed). |
+
+### ModelHandle
+
+The return value exposes everything a component needs to render and interact with the form:
+
+| Property | Type | Description |
+|---|---|---|
+| `state` | `S` | Current frozen state — read raw field values here. |
+| `errors` | `ValidationErrors<S>` | Validation errors keyed by field name. Empty object when valid. |
+| `valid` | `boolean` | `true` when `errors` has no keys — all fields pass validation. |
+| `dirty` | `boolean` | `true` when `state` differs from the committed baseline (shallow equality). |
+| `model` | `M` | The Model instance itself — call setter methods on this. |
+
+---
+
+## Lifecycle
+
+### Mount
+
+1. The `factory` is called during render to create the Model instance.
+2. On mount (inside `useEffect`), `init()` is called automatically if the instance has an `init` method.
+3. `useSyncExternalStore` subscribes to the Model — any `set()` call triggers a React re-render.
+
+### Re-render
+
+On subsequent renders, the existing instance is reused. The factory is **not** called again. `init()` is **not** called again — it is idempotent.
+
+### Unmount
+
+On unmount, `dispose()` is called after a deferred `setTimeout(0)`. The defer handles React Strict Mode's mount/unmount/remount cycle — if the component remounts immediately, dispose is cancelled.
+
+After dispose:
+- `set()` throws
+- `commit()` / `rollback()` throw
+- `subscribe()` returns a no-op
+
+### Passing an External Model
+
+When a ViewModel owns the Model (the typical form-page pattern), pass it through the factory:
+
+```tsx
+function EditUserForm({ model }: { model: UserFormModel }) {
+  const { state, errors, valid, dirty } = useModel(() => model);
+  // ...
+}
+```
+
+The hook subscribes to whichever instance the factory returns. Lifecycle (`init`/`dispose`) still applies — the hook auto-initializes and auto-disposes the instance it holds.
+
+---
+
+## Basic Usage
+
+### Define a Model
+
+```typescript
+import { Model } from 'mvc-kit';
+import type { ValidationErrors } from 'mvc-kit';
+
+interface FormState {
+  name: string;
+  email: string;
+  age: number;
+}
+
+class FormModel extends Model<FormState> {
+  setName(name: string) { this.set({ name }); }
+  setEmail(email: string) { this.set({ email }); }
+  setAge(age: number) { this.set({ age }); }
+
+  protected validate(state: Readonly<FormState>): ValidationErrors<FormState> {
+    const errors: ValidationErrors<FormState> = {};
+    if (!state.name) errors.name = 'Name is required';
+    if (!state.email.includes('@')) errors.email = 'Invalid email';
+    if (state.age < 0) errors.age = 'Age must be positive';
+    return errors;
+  }
+}
+```
+
+### Bind to a Component
+
+```tsx
+import { useModel } from 'mvc-kit/react';
+
+function UserForm() {
+  const { state, errors, valid, dirty, model } = useModel(
+    () => new FormModel({ name: '', email: '', age: 0 })
+  );
+
+  return (
+    <form>
+      <input value={state.name} onChange={e => model.setName(e.target.value)} />
+      {errors.name && <span className="error">{errors.name}</span>}
+
+      <input value={state.email} onChange={e => model.setEmail(e.target.value)} />
+      {errors.email && <span className="error">{errors.email}</span>}
+
+      <button disabled={!valid || !dirty}>Save</button>
+    </form>
+  );
+}
+```
+
+`state.x` for raw values. `errors.x` for field errors. `model.setX()` for mutations. `valid` and `dirty` for button/form state.
+
+---
+
+## Model Inside a ViewModel
+
+The typical form-page pattern: a [ViewModel](../ViewModel.md) handles async operations (load, save, delete) and coordination, while the Model handles the editing state. The ViewModel owns the Model and disposes it in `onDispose()`.
+
+```typescript
+interface EditState {
+  draft: UserState | null;
+}
+
+interface EditEvents {
+  saved: { id: string };
+}
+
+class EditUserViewModel extends ViewModel<EditState, EditEvents> {
+  public model!: UserFormModel;
+  private service = singleton(UserService);
+
+  protected async onInit() {
+    const user = await this.service.getById(this.userId, this.disposeSignal);
+    this.model = new UserFormModel(user);
+    this.set({ draft: user });
+  }
+
+  async save() {
+    if (!this.model.valid) return;
+    await this.service.update(this.userId, this.model.state, this.disposeSignal);
+    this.model.commit();
+    this.emit('saved', { id: this.userId });
+  }
+
+  protected onDispose() {
+    this.model?.dispose();
+  }
+}
+```
+
+```tsx
+function EditUserPage() {
+  const [state, vm] = useLocal(EditUserViewModel, { draft: null });
+  const loadState = vm.async.onInit;
+  const saveState = vm.async.save;
+
+  if (loadState.loading || !vm.model) return <Spinner />;
+  if (loadState.error) return <ErrorBanner message={loadState.error} />;
+
+  return <EditUserForm model={vm.model} onSave={() => vm.save()} saving={saveState.loading} />;
+}
+
+function EditUserForm({ model, onSave, saving }: Props) {
+  const { state, errors, valid, dirty } = useModel(() => model);
+
+  return (
+    <form onSubmit={e => { e.preventDefault(); onSave(); }}>
+      <input value={state.name} onChange={e => model.setName(e.target.value)} />
+      {errors.name && <span>{errors.name}</span>}
+      <button disabled={!valid || !dirty || saving}>
+        {saving ? 'Saving...' : 'Save'}
+      </button>
+    </form>
+  );
+}
+```
+
+---
+
+## useModelRef
+
+Create a component-scoped Model with lifecycle management (init + dispose) but **no state subscription**. The parent component never re-renders from model state changes.
+
+Designed for the per-field isolation pattern: parent creates the model via `useModelRef`, children subscribe to individual fields via `useField`.
+
+### Signature
+
+```typescript
+function useModelRef<M extends Model<any>>(factory: () => M): M;
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `factory` | `() => M` | Factory that returns a Model instance. Called once on mount (or if the previous instance was disposed). |
+
+**Returns:** `M` — the Model instance directly. No `state`, `errors`, `valid`, or `dirty` — read those in child components via `useField` or `useInstance`.
+
+### Lifecycle
+
+Same as `useModel`: auto-calls `init()` on mount, auto-calls `dispose()` on unmount (deferred for StrictMode safety). The only difference is **no `useSyncExternalStore` subscription** — the parent never re-renders from model changes.
+
+### Usage — Per-Field Form
+
+```tsx
+import { Model } from 'mvc-kit';
+import { useModelRef, useField, useInstance } from 'mvc-kit/react';
+
+class FormModel extends Model<FormState> {
+  protected validate(state: FormState): ValidationErrors<FormState> {
+    const errors: ValidationErrors<FormState> = {};
+    if (!state.name) errors.name = 'Name is required';
+    if (!state.email.includes('@')) errors.email = 'Invalid email';
+    return errors;
+  }
+}
+
+// Parent — creates model, never re-renders from field changes
+function UserForm() {
+  const model = useModelRef(() => new FormModel({ name: '', email: '' }));
+  return (
+    <form>
+      <NameField model={model} />
+      <EmailField model={model} />
+      <FormActions model={model} />
+    </form>
+  );
+}
+
+// Per-field child — only re-renders when its field changes
+function NameField({ model }: { model: FormModel }) {
+  const { value, error, set } = useField(model, 'name');
+  return (
+    <div>
+      <input value={value} onChange={e => set(e.target.value)} />
+      {error && <span className="error">{error}</span>}
+    </div>
+  );
+}
+
+// Submit button — subscribes to full model for valid/dirty
+function FormActions({ model }: { model: FormModel }) {
+  useInstance(model);
+  return <button disabled={!model.valid || !model.dirty}>Save</button>;
+}
+```
+
+### When to Use useModelRef vs useModel
+
+| Scenario | Hook | Why |
+|---|---|---|
+| Simple form (few fields, one component) | `useModel` | Component needs `state`, `errors`, `valid`, `dirty` directly |
+| Large form (many fields, per-field components) | `useModelRef` | Parent doesn't subscribe — only changed fields re-render |
+| Submit button / form actions | `useInstance(model)` | Subscribe to full model without owning lifecycle |
+
+> **Important:** Don't use `useModel` in the parent when children use `useField` — `useModel` subscribes to all state changes, which defeats per-field isolation. The parent would re-render on every keystroke, negating the benefit.
+
+---
+
+## useField
+
+Subscribe to a **single field** with surgical re-renders. The component only re-renders when that specific field's value or error changes — other fields updating on the same Model are ignored.
+
+### Signature
+
+```typescript
+function useField<S extends object, K extends keyof S>(
+  model: Model<S>,
+  field: K
+): FieldHandle<S[K]>;
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `model` | `Model<S>` | The Model instance (must already be created — typically via `useModelRef`, `useModel`, or a ViewModel). |
+| `field` | `K` | The state key to subscribe to. Type-safe — invalid keys produce a compile-time error. |
+
+### FieldHandle
+
+| Property | Type | Description |
+|---|---|---|
+| `value` | `S[K]` | Current value of the field. |
+| `error` | `string \| undefined` | Validation error for this field, or `undefined` if valid. |
+| `set` | `(value: S[K]) => void` | Update the field value directly via `model.set({ [field]: value })`. |
+
+### Usage
+
+```tsx
+import { useField } from 'mvc-kit/react';
+
+function NameField({ model }: { model: FormModel }) {
+  const { value, error, set } = useField(model, 'name');
+
+  return (
+    <div>
+      <input value={value} onChange={e => set(e.target.value)} />
+      {error && <span className="error">{error}</span>}
+    </div>
+  );
+}
+```
+
+### When to Use useField vs useModel vs useModelRef
+
+| Scenario | Hook |
+|---|---|
+| Simple form with a few fields | `useModel` — one component renders everything |
+| Large form with many fields | `useModelRef` in parent + `useField` in children — only changed fields re-render |
+| Reading `valid` / `dirty` for submit button state | `useInstance(model)` in a leaf component — subscribe without owning lifecycle |
+| Individual field input + error display | `useField` — surgical re-renders |
+
+### Selective Re-renders
+
+`useField` compares field value and error by reference (`!==`) on every Model notification. If a different field changes, the comparison short-circuits and no re-render occurs:
+
+```tsx
+// Only re-renders when `name` value or `name` error changes.
+// Changing `email` or `age` on the same model does NOT trigger a re-render here.
+const { value, error, set } = useField(model, 'name');
+```
+
+### Type Safety
+
+`useField` rejects invalid field names at compile time:
+
+```typescript
+useField(model, 'name');          // OK
+useField(model, 'email');         // OK
+useField(model, 'invalidField');  // Compile error — 'invalidField' is not a key of FormState
+```
+
+---
+
+## Best Practices
+
+**Use named setters on the Model, not `set()` directly.** `set()` is protected. Expose intent-based setters (`setName`, `setEmail`) on your Model subclass.
+
+**Read `state.x` for values, `errors.x` for errors.** Don't derive validation in the component — the Model handles it automatically via `validate()`.
+
+**Use `valid` and `dirty` for button state.** Disable submit when `!valid || !dirty`. After a successful save, call `model.commit()` to reset `dirty` to `false`.
+
+**Split large forms into per-field components with `useField`.** Each field component only re-renders when its own value or error changes.
+
+**Let the ViewModel own the Model for form pages.** The ViewModel handles load/save/delete. The Model handles editing. The component just renders. See [Model inside a ViewModel](#model-inside-a-viewmodel).
+
+**Don't put async logic in a Model.** Models are for synchronous editing state (values, validation, dirty tracking). Async operations (save, load, delete) belong in a [ViewModel](../ViewModel.md) that owns the Model.
+
+---
+
+## Related
+
+- [Model](../Model.md) — the base class: validation, dirty tracking, commit/rollback
+- [ViewModel](../ViewModel.md) — async tracking, computed getters, events
+- [useLocal](./use-local.ts) — component-scoped ViewModel hook (the ViewModel equivalent of `useModel`)