mvc-kit 2.12.0 → 2.12.2

package/src/react/use-local.md

@@ -0,0 +1,457 @@
+# useLocal
+
+Creates a component-scoped instance, auto-initialized on mount and auto-disposed on unmount. This is the primary hook for connecting a [ViewModel](../ViewModel.md) or [Controller](../Controller.md) to a React component.
+
+---
+
+## Signatures
+
+### Subscribable (class + initialState)
+
+```typescript
+function useLocal<T extends Subscribable & Disposable>(
+  Class: new (initialState: StateOf<T>) => T,
+  initialState: StateOf<T>,
+): [Readonly<StateOf<T>>, T];
+```
+
+### Subscribable (factory)
+
+```typescript
+function useLocal<T extends Subscribable<S> & Disposable, S>(
+  factory: () => T,
+): [S, T];
+```
+
+### Disposable-only (class)
+
+```typescript
+function useLocal<T extends Disposable>(
+  Class: new (...args: Args) => T,
+  ...args: Args,
+): T;
+```
+
+### Disposable-only (factory)
+
+```typescript
+function useLocal<T extends Disposable>(
+  factory: () => T,
+): T;
+```
+
+All four signatures accept an optional `deps: DependencyList` as the final argument. See [Dependencies](#dependencies).
+
+---
+
+## Return Value
+
+The return type depends on whether the instance implements `Subscribable`:
+
+| Instance type | Return | Example |
+|---|---|---|
+| **Subscribable** (ViewModel, Collection, Model) | `[S, T]` — state tuple | `const [state, vm] = useLocal(MyVM, { ... })` |
+| **Subscribe-only** (Trackable) | `T` — the instance, with automatic re-renders | `const query = useLocal(MyQuery)` |
+| **Disposable-only** (Controller) | `T` — the instance directly | `const ctrl = useLocal(MyController)` |
+
+The distinction is duck-typed at runtime: if the instance has a `state` property and a `subscribe` method, it's treated as Subscribable (tuple return). If it has `subscribe` but no `state` (e.g., Trackable), it returns the instance directly but sets up a version-counter subscription so changes trigger re-renders.
+
+---
+
+## Lifecycle
+
+### Mount
+
+1. **Instance creation** — the class is constructed (or factory is called) during the render phase. The instance is created once and reused across re-renders via a `useRef`.
+2. **Initialization** — `init()` is called in a `useEffect` after React commits the render. If the instance has an `init` method (duck-typed via `isInitializable`), it is called automatically. For ViewModels, this triggers `_trackSubscribables`, `_processMembers` (getter memoization + async method wrapping), and `onInit()`.
+3. **Subscription** — if the instance is Subscribable, `useSyncExternalStore` subscribes to both state changes and async state changes (via `subscribeAsync` when available).
+
+### Re-render
+
+The same instance is reused. No new construction or initialization. Re-renders are triggered by:
+
+- `set()` calls that produce a new state reference
+- Subscribable member notifications (Collection, Channel)
+- Async method status changes (loading start, completion, error)
+
+### Unmount
+
+Dispose is **deferred** via `setTimeout(0)`. This is critical for React StrictMode compatibility — StrictMode's development-only unmount/remount cycle completes before the timeout fires. If the component remounts (StrictMode), the `mountedRef` check prevents disposal. If the component truly unmounts, `dispose()` runs after the timeout.
+
+```
+mount → init() → ... → unmount → setTimeout → dispose()
+                                                ↳ aborts disposeSignal
+                                                ↳ tears down subscriptions
+                                                ↳ runs addCleanup callbacks
+                                                ↳ disposes event bus
+                                                ↳ calls onDispose()
+```
+
+---
+
+## Usage
+
+### ViewModel with initial state
+
+The most common pattern. Pass the class and initial state as separate arguments.
+
+```tsx
+function LocationsPage() {
+  const [state, vm] = useLocal(LocationsViewModel, {
+    items: [],
+    search: '',
+    typeFilter: 'all',
+  });
+  const { loading, error } = vm.async.load;
+
+  return (
+    <div>
+      <input value={state.search} onChange={e => vm.setSearch(e.target.value)} />
+      {loading && <Spinner />}
+      {error && <ErrorBanner message={error} />}
+      <LocationsTable locations={vm.filtered} />
+    </div>
+  );
+}
+```
+
+- `state` — the frozen state object, updated by `set()` calls inside the ViewModel
+- `vm` — the ViewModel instance, used to access getters (`vm.filtered`), async status (`vm.async.load`), and call actions (`vm.setSearch()`)
+
+### ViewModel with factory
+
+Use the factory overload when the constructor has a non-standard signature or when you need to capture closure variables.
+
+```tsx
+function ChatPage({ roomId }: { roomId: string }) {
+  const [state, vm] = useLocal(() => new ChatViewModel(roomId));
+  return <ChatMessages messages={state.messages} />;
+}
+```
+
+### Controller (Disposable-only)
+
+When the instance doesn't implement `Subscribable` (no `state` property or `subscribe` method), `useLocal` returns the instance directly instead of a tuple.
+
+```tsx
+function WorkflowPage() {
+  const ctrl = useLocal(DragDropController);
+  const [count, setCount] = useState(0);
+
+  return <button onClick={() => setCount(ctrl.increment())}>Go</button>;
+}
+```
+
+Controllers still get full lifecycle management — `init()` on mount, `dispose()` on unmount.
+
+### Controller with factory
+
+```tsx
+function WorkflowPage({ config }: { config: string }) {
+  const ctrl = useLocal(() => new ConfigurableController(config));
+  return <div>{ctrl.config}</div>;
+}
+```
+
+### Trackable (subscribe-only)
+
+Custom reactive objects that extend `Trackable` return the instance directly. Changes trigger re-renders via the subscribe-only version-counter path.
+
+```tsx
+function UserSearch() {
+  const query = useLocal(() => new RPCQuery<string, User[]>('Users.Search'));
+
+  return (
+    <div>
+      {query.loading && <Spinner />}
+      {query.data?.map(user => <UserCard key={user.id} user={user} />)}
+      <button onClick={() => query.call('alice')}>Search</button>
+    </div>
+  );
+}
+```
+
+The instance is disposed on unmount and supports `deps` for recreation. See [Trackable](../Trackable.md) for details.
+
+### Collection
+
+Collections implement `Subscribable`, so they return a state tuple. The state is the items array.
+
+```tsx
+function TodoList() {
+  const [items, collection] = useLocal(TodoCollection);
+  return (
+    <div>
+      <span>{items.length} items</span>
+      <button onClick={() => collection.add({ id: '1', text: 'New', done: false })}>
+        Add
+      </button>
+    </div>
+  );
+}
+```
+
+---
+
+## Dependencies
+
+All signatures accept an optional `deps` array as the final argument. When any dependency value changes (compared via `Object.is`), the current instance is **disposed** and a **new instance** is created and initialized.
+
+### Class + initialState + deps
+
+```tsx
+function UserPage({ userId }: { userId: string }) {
+  const [state, vm] = useLocal(UserViewModel, { userId, data: null }, [userId]);
+  const { loading, error } = vm.async.load;
+
+  return (
+    <div>
+      {loading && <Spinner />}
+      {error && <ErrorBanner message={error} />}
+      {state.data && <UserProfile user={state.data} />}
+    </div>
+  );
+}
+```
+
+When `userId` changes:
+
+1. The old instance is disposed (render-phase synchronous dispose)
+2. Its `disposeSignal` is aborted — cancelling in-flight fetches
+3. A new instance is constructed with the new `userId` in initial state
+4. The `useEffect` cleanup fires for the old instance, the new effect runs `init()`
+5. `onInit()` executes on the fresh instance with the new state
+
+### Factory + deps
+
+```tsx
+const [state, vm] = useLocal(() => new ChatViewModel(roomId), [roomId]);
+```
+
+### Disposable + deps
+
+Works with Controllers too — the instance is disposed and recreated.
+
+```tsx
+function Room({ roomId }: { roomId: string }) {
+  const ctrl = useLocal(() => new TimerController(roomId), [roomId]);
+  return <div>{ctrl.id}</div>;
+}
+```
+
+### Multiple dependencies
+
+Any element changing triggers dispose/recreate.
+
+```tsx
+const [state, vm] = useLocal(MultiVM, { a, b, data: null }, [a, b]);
+```
+
+### Stable deps
+
+When deps haven't changed (by `Object.is`), the same instance is reused — no disposal, no reconstruction.
+
+### Rapid dep changes
+
+If deps change multiple times before effects settle, each intermediate instance is disposed synchronously during the render phase. Only the final instance survives. This is safe because:
+
+- Render-phase dispose aborts the `disposeSignal` on each stale instance
+- In-flight fetches using `disposeSignal` throw `AbortError` and are swallowed
+- `set()` on a disposed instance is a no-op — stale responses can't corrupt the active instance
+
+```
+userId: 1 → 2 → 3 → 4
+
+Instance 1: created → disposed (render phase)
+Instance 2: created → disposed (render phase)
+Instance 3: created → disposed (render phase)
+Instance 4: created → init() → active ✓
+```
+
+---
+
+## React StrictMode
+
+`useLocal` is fully compatible with React StrictMode's development-only double-mount cycle.
+
+**How it works:** Dispose is deferred via `setTimeout(0)`. During StrictMode's unmount/remount:
+
+1. First mount: instance created, effect runs `init()`
+2. StrictMode unmount: cleanup schedules deferred dispose
+3. StrictMode remount: `mountedRef` is set to `true` before the timeout fires
+4. Timeout fires: `mountedRef` is `true`, so dispose is skipped
+
+The result:
+
+- `onInit()` is called exactly once
+- `disposeSignal` is NOT aborted during the fake unmount
+- The instance survives the StrictMode cycle intact
+
+On real unmount, `mountedRef` stays `false` and dispose proceeds normally.
+
+---
+
+## Async Status
+
+When using `useLocal` with a [ViewModel](../ViewModel.md), async method status is automatically tracked and triggers re-renders.
+
+```tsx
+function ItemPage() {
+  const [state, vm] = useLocal(ItemViewModel, { items: [] });
+  const loadState = vm.async.load;
+  const saveState = vm.async.save;
+
+  return (
+    <div>
+      {loadState.loading && <Spinner />}
+      {loadState.error && <ErrorBanner message={loadState.error} />}
+      <form onSubmit={e => { e.preventDefault(); vm.save(); }}>
+        <button disabled={saveState.loading}>
+          {saveState.loading ? 'Saving…' : 'Save'}
+        </button>
+        {saveState.error && <p className="error">{saveState.error}</p>}
+      </form>
+    </div>
+  );
+}
+```
+
+`useLocal` subscribes to async state changes via `subscribeAsync()` (duck-typed). When any async method's `TaskState` changes, React re-renders. See [ViewModel — Async Tracking](../ViewModel.md#async-tracking) for details.
+
+---
+
+## Stale Response Protection
+
+Two safety layers prevent disposed instances from corrupting the active UI:
+
+### Layer 1: disposeSignal
+
+Pass `this.disposeSignal` to `fetch()` and service calls. When the instance is disposed, the signal aborts, `fetch` throws `AbortError`, and async tracking swallows it silently.
+
+```typescript
+async load() {
+  const data = await this.service.getUser(userId, this.disposeSignal);
+  this.set({ data }); // never reached if signal was aborted
+}
+```
+
+### Layer 2: set() no-op after dispose
+
+Even without `disposeSignal`, `set()` on a disposed instance is a silent no-op. If a slow response arrives after the instance was disposed, the `set()` call does nothing.
+
+```typescript
+// Even if this fetch completes after dispose, set() is harmless
+async load() {
+  const res = await fetch(`/api/users/${userId}`);
+  const data = await res.json();
+  this.set({ data }); // no-op if disposed
+}
+```
+
+**Best practice:** Always use `disposeSignal` (Layer 1). It cancels the network request early, saving bandwidth and preventing unnecessary work. Layer 2 is defense-in-depth.
+
+---
+
+## Error Isolation
+
+When using deps, each instance has independent async tracking. An error on one instance does not bleed into the next.
+
+```
+userId: "bad-user" → "good-user"
+
+Instance 1 (bad-user): load() → 500 error → vm.async.load.error = "Internal Server Error"
+  ↳ disposed on dep change
+Instance 2 (good-user): load() → success → vm.async.load.error = null (clean slate)
+```
+
+The new instance starts with a fresh `{ loading: false, error: null, errorCode: null }` for every method.
+
+---
+
+## Signal Propagation
+
+`disposeSignal` propagates through the entire call chain — from the ViewModel through services to the underlying `fetch()`. When deps change and the old instance is disposed:
+
+- All `fetch()` calls using `disposeSignal` abort at the network level
+- Multiple parallel fetches (e.g., `Promise.all`) all abort
+- `AbortError` is swallowed by async tracking — no unhandled rejections
+
+```typescript
+async load() {
+  // Both fetches abort when disposeSignal fires
+  const [data, profile] = await Promise.all([
+    fetch(`/api/users/${userId}`, { signal: this.disposeSignal }).then(r => r.json()),
+    fetch(`/api/profiles/${userId}`, { signal: this.disposeSignal }).then(r => r.json()),
+  ]);
+  this.set({ data, profile });
+}
+```
+
+---
+
+## Best Practices
+
+**One `useLocal` per component.** If a component needs two ViewModels, split it into two components. Each connected component owns exactly one ViewModel.
+
+**Don't call `init()` manually.** `useLocal` calls it automatically after mount. Don't double-init.
+
+**Don't call `dispose()` manually.** `useLocal` handles teardown on unmount.
+
+**Don't put loading/error in state.** Read from `vm.async.methodName` instead. See [ViewModel — Async Tracking](../ViewModel.md#async-tracking).
+
+**Don't fetch in `useEffect`.** Use `onInit()` inside the ViewModel instead. `useLocal` calls `init()` which calls `onInit()` — the ViewModel manages its own initialization.
+
+**Use deps for route params and dynamic props.** When a prop changes and the ViewModel needs to tear down and reinitialize (new data, new subscriptions), pass that prop in the deps array.
+
+**Pass `disposeSignal` to every async call.** Ensures in-flight requests cancel on unmount or dep change.
+
+---
+
+## Anti-Patterns
+
+### Multiple useLocal in one component
+
+```tsx
+// Bad — split into two components
+const [s1, vm1] = useLocal(UsersViewModel, { ... });
+const [s2, vm2] = useLocal(OnDutyViewModel, { ... });
+```
+
+### Fetching in useEffect
+
+```tsx
+// Bad — ViewModel handles its own initialization
+useEffect(() => { vm.load(); }, []);
+
+// Good — onInit() handles it; useLocal calls init() automatically
+```
+
+### Manual init/dispose
+
+```tsx
+// Bad — useLocal manages the lifecycle
+useEffect(() => {
+  vm.init();
+  return () => vm.dispose();
+}, []);
+```
+
+### Derived state in the component
+
+```tsx
+// Bad — filtering belongs in a ViewModel getter
+const filtered = state.items.filter(i => i.active);
+
+// Good — read the getter
+<ItemList items={vm.filtered} />
+```
+
+---
+
+## Related
+
+- [ViewModel](../ViewModel.md) — the primary class used with `useLocal`
+- [Controller](../Controller.md) — stateless orchestrator, returns instance directly
+- [Trackable](../Trackable.md) — base class for custom reactive objects, returns instance with auto re-renders
+- [Collection](../Collection.md) — reactive typed array, returns `[items, collection]`
+- [Model](../Model.md) — entity with validation; typically used via `useModel` instead