mvc-kit 2.12.0 → 2.12.1

package/src/react/use-instance.md

@@ -0,0 +1,204 @@
+# useInstance
+
+A low-level React hook that subscribes to any [Subscribable](../types.ts) instance and returns its current state. The caller manages the instance lifecycle — `useInstance` only reads and subscribes; it never creates, initializes, or disposes.
+
+---
+
+## Signature
+
+```typescript
+function useInstance<S>(subscribable: Subscribable<S>): S
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `subscribable` | `Subscribable<S>` | Any object with `state` and `subscribe(listener)`. [ViewModel](../ViewModel.md), [Model](../Model.md), [Collection](../Collection.md), [Channel](../Channel.md) all qualify. |
+
+**Returns:** `S` — the current frozen state of the subscribable. Re-renders the component whenever the state changes.
+
+---
+
+## How It Works
+
+`useInstance` uses a single `useSyncExternalStore` call with a **version counter** for change detection.
+
+### Single Combined Subscription
+
+A `useRef`-stored `subscribe` function wires up both the state subscription (`subscribable.subscribe`) and, if present (duck-typed check), the async subscription (`subscribable.subscribeAsync`). Both increment a version counter and call `onStoreChange`. The subscribe and getSnapshot functions are stored in a ref and only recreated when the subscribable instance changes, avoiding `useCallback` deps-checking overhead on every render.
+
+React detects changes via `Object.is(prevVersion, nextVersion)` on the counter rather than comparing state references. The actual state is read directly from `subscribable.state` in the render body.
+
+This means:
+- **ViewModel** — both state and async subscriptions are active. `vm.async.load.loading` changes trigger re-renders.
+- **Collection**, **Model**, **Channel** — only the state subscription is active. These classes don't have `subscribeAsync`, so no async subscription is created.
+
+### Why a version counter?
+
+Subscribable member notifications (e.g., a Collection changing inside a ViewModel) don't produce a new state reference — the ViewModel's state object is unchanged, only its getters return different results. The version counter ensures React re-renders in these cases without forcing an unnecessary state object spread.
+
+---
+
+## When to Use
+
+Use `useInstance` when you have a **pre-existing instance** that you didn't create and don't own. Common scenarios:
+
+- A parent component creates a ViewModel via `useLocal` and passes it to a child
+- A ViewModel exposes a Model as a public property (`vm.model`)
+- You need to read state from a singleton obtained elsewhere
+
+```tsx
+function ChildDisplay({ vm }: { vm: ParentViewModel }) {
+  const state = useInstance(vm);
+  return <p>{state.count}</p>;
+}
+```
+
+### When NOT to Use
+
+| Scenario | Use Instead |
+|---|---|
+| Creating a component-scoped ViewModel | [`useLocal`](./use-local.md) — creates, initializes, disposes automatically |
+| Sharing a singleton ViewModel across components | [`useSingleton`](./use-singleton.md) — singleton lifecycle management |
+| Binding a Model with validation/dirty tracking | [`useModel`](./use-model.md) — returns `ModelHandle` with `errors`, `valid`, `dirty` |
+| Creating a Model for per-field children | [`useModelRef`](./use-model.md) — lifecycle without subscription |
+| Binding a single Model field | [`useField`](./use-model.md) — surgical per-field re-renders |
+
+`useInstance` returns raw state only. It doesn't provide validation errors, dirty tracking, or any Model-specific features.
+
+---
+
+## Usage
+
+### With ViewModel
+
+```tsx
+function CounterDisplay({ vm }: { vm: CounterViewModel }) {
+  const state = useInstance(vm);
+  return <div>{state.count}</div>;
+}
+```
+
+State changes via `vm.set()` trigger re-renders. Computed getters are accessed on the instance, not from the returned state:
+
+```tsx
+function LocationsList({ vm }: { vm: LocationsViewModel }) {
+  const state = useInstance(vm);
+  return (
+    <div>
+      <p>Search: {state.search}</p>
+      <p>Filtered: {vm.filtered.length} of {vm.total}</p>
+    </div>
+  );
+}
+```
+
+### With ViewModel Async State
+
+Because `useInstance` subscribes to `subscribeAsync` on ViewModels, reading `vm.async` in the render body works correctly — the component re-renders when loading or error state changes:
+
+```tsx
+function AsyncDisplay({ vm }: { vm: DataViewModel }) {
+  useInstance(vm);
+  const { loading, error } = vm.async.load;
+
+  return (
+    <div>
+      {loading && <p>Loading...</p>}
+      {error && <p className="error">{error}</p>}
+    </div>
+  );
+}
+```
+
+The returned state can be ignored (assigned to nothing) if you only need async status and computed getters.
+
+### With Model
+
+```tsx
+function UserDisplay({ model }: { model: UserModel }) {
+  const state = useInstance(model);
+  return <p>{state.name}</p>;
+}
+```
+
+State changes via `model.set()` trigger re-renders. Note: this gives you raw state only — no `errors`, `valid`, or `dirty`. For full form binding, use `useModel` instead.
+
+### With Collection
+
+Collection state is the items array itself:
+
+```tsx
+function TodoList({ collection }: { collection: Collection<Todo> }) {
+  const items = useInstance(collection);
+  return (
+    <ul>
+      {items.map(item => <li key={item.id}>{item.text}</li>)}
+    </ul>
+  );
+}
+```
+
+Mutations like `collection.add()`, `collection.remove()`, and `collection.reset()` trigger re-renders.
+
+> **Note:** Components should rarely subscribe to a Collection directly. The standard pattern is for a [ViewModel](../ViewModel.md) to mirror collection data into its own state via `subscribeTo`. Direct Collection subscription is appropriate only in low-level or infrastructure components.
+
+---
+
+## Lifecycle Responsibility
+
+`useInstance` does **not** manage lifecycle. The caller is responsible for:
+
+1. **Creating** the instance before passing it
+2. **Calling `init()`** if the instance requires initialization (ViewModels)
+3. **Calling `dispose()`** when the instance is no longer needed
+
+```tsx
+function Parent() {
+  const [state, vm] = useLocal(ParentViewModel, { count: 0 });
+
+  return (
+    <div>
+      {/* vm is created, initialized, and disposed by useLocal */}
+      {/* ChildDisplay just reads from it */}
+      <ChildDisplay vm={vm} />
+      <button onClick={() => vm.increment()}>+</button>
+    </div>
+  );
+}
+
+function ChildDisplay({ vm }: { vm: ParentViewModel }) {
+  const state = useInstance(vm);
+  return <p>{state.count}</p>;
+}
+```
+
+---
+
+## Cleanup
+
+The combined subscription cleanup function is called automatically when the component unmounts, unsubscribing from both `subscribe()` and `subscribeAsync()` (if present).
+
+After unmount, further state changes on the instance do not cause errors — the subscriptions are simply gone.
+
+---
+
+## SSR
+
+The `useSyncExternalStore` call provides a server snapshot that returns `0` (the initial version counter value). The actual state is read from `subscribable.state` directly.
+
+---
+
+## Best Practices
+
+**Use `useInstance` for read-only binding to instances you don't own.** If you're creating the instance, use `useLocal` or `useSingleton` instead.
+
+**Access computed getters on the instance, raw state from the return value.**
+
+```tsx
+const state = useInstance(vm);
+// state.search     — raw state value
+// vm.filtered      — computed getter
+// vm.async.load    — async status
+```
+
+**Don't forget to init before passing.** If you pass an uninitialized ViewModel to `useInstance`, async tracking won't be active and memoized getters won't work. Always ensure `init()` has been called (or use `useLocal` which calls it automatically).

package/src/react/use-instance.test.tsx

@@ -0,0 +1,350 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { render, screen, act } from '@testing-library/react';
+import { ViewModel } from '../ViewModel';
+import { Model } from '../Model';
+import { Collection } from '../Collection';
+import { useInstance } from './use-instance';
+
+interface CounterState {
+  count: number;
+}
+
+class CounterVM extends ViewModel<CounterState> {
+  constructor(initial = 0) {
+    super({ count: initial });
+  }
+
+  increment() {
+    this.set((prev) => ({ count: prev.count + 1 }));
+  }
+
+  decrement() {
+    this.set((prev) => ({ count: prev.count - 1 }));
+  }
+}
+
+function CounterDisplay({ vm }: { vm: CounterVM }) {
+  const state = useInstance(vm);
+  return <div data-testid="count">{state.count}</div>;
+}
+
+describe('useInstance', () => {
+  it('should return the current state', () => {
+    const vm = new CounterVM(5);
+    render(<CounterDisplay vm={vm} />);
+    expect(screen.getByTestId('count').textContent).toBe('5');
+  });
+
+  it('should re-render when state changes', () => {
+    const vm = new CounterVM(0);
+    render(<CounterDisplay vm={vm} />);
+    expect(screen.getByTestId('count').textContent).toBe('0');
+
+    act(() => {
+      vm.increment();
+    });
+
+    expect(screen.getByTestId('count').textContent).toBe('1');
+  });
+
+  it('should handle multiple state updates', () => {
+    const vm = new CounterVM(0);
+    render(<CounterDisplay vm={vm} />);
+
+    act(() => {
+      vm.increment();
+      vm.increment();
+      vm.increment();
+    });
+
+    expect(screen.getByTestId('count').textContent).toBe('3');
+  });
+
+  it('should work with initial state from constructor', () => {
+    const vm = new CounterVM(100);
+    render(<CounterDisplay vm={vm} />);
+    expect(screen.getByTestId('count').textContent).toBe('100');
+  });
+
+  describe('with Model', () => {
+    interface UserState {
+      name: string;
+      email: string;
+    }
+
+    class UserModel extends Model<UserState> {
+      setName(name: string) {
+        this.set({ name });
+      }
+    }
+
+    function UserDisplay({ model }: { model: UserModel }) {
+      const state = useInstance(model);
+      return <div data-testid="name">{state.name}</div>;
+    }
+
+    it('should work with Model instances', () => {
+      const model = new UserModel({ name: 'John', email: 'john@example.com' });
+      render(<UserDisplay model={model} />);
+      expect(screen.getByTestId('name').textContent).toBe('John');
+
+      act(() => {
+        model.setName('Jane');
+      });
+
+      expect(screen.getByTestId('name').textContent).toBe('Jane');
+    });
+  });
+
+  describe('with Collection', () => {
+    interface Todo {
+      id: string;
+      text: string;
+    }
+
+    function TodoList({ collection }: { collection: Collection<Todo> }) {
+      const items = useInstance(collection);
+      return (
+        <ul data-testid="list">
+          {items.map(item => <li key={item.id}>{item.text}</li>)}
+        </ul>
+      );
+    }
+
+    it('should work with Collection instances', () => {
+      const collection = new Collection<Todo>([{ id: '1', text: 'Test' }]);
+      render(<TodoList collection={collection} />);
+      expect(screen.getByTestId('list').children).toHaveLength(1);
+
+      act(() => {
+        collection.add({ id: '2', text: 'Another' });
+      });
+
+      expect(screen.getByTestId('list').children).toHaveLength(2);
+    });
+  });
+
+  it('does not re-subscribe on re-render (stable callback identity)', () => {
+    const subscribeSpy = vi.spyOn(CounterVM.prototype, 'subscribe');
+    const vm = new CounterVM(0);
+    vm.init();
+
+    const { rerender } = render(<CounterDisplay vm={vm} />);
+
+    const initialCallCount = subscribeSpy.mock.calls.length;
+
+    // Force multiple re-renders — subscribe should NOT be called again
+    rerender(<CounterDisplay vm={vm} />);
+    rerender(<CounterDisplay vm={vm} />);
+    rerender(<CounterDisplay vm={vm} />);
+
+    expect(subscribeSpy.mock.calls.length).toBe(initialCallCount);
+    subscribeSpy.mockRestore();
+  });
+
+  it('re-renders when subscribable member changes (via version counter)', () => {
+    interface DashState {
+      label: string;
+    }
+
+    class DashVM extends ViewModel<DashState> {
+      collection = new Collection<{ id: string; name: string }>();
+
+      get items() {
+        return this.collection.items;
+      }
+    }
+
+    let renderCount = 0;
+    function DashDisplay({ vm }: { vm: DashVM }) {
+      const state = useInstance(vm);
+      renderCount++;
+      return (
+        <div>
+          <span data-testid="label">{state.label}</span>
+          <span data-testid="count">{vm.items.length}</span>
+        </div>
+      );
+    }
+
+    const vm = new DashVM({ label: 'test' });
+    vm.init();
+    renderCount = 0;
+
+    render(<DashDisplay vm={vm} />);
+    const rendersAfterMount = renderCount;
+
+    act(() => {
+      vm.collection.add({ id: '1', name: 'Alice' });
+    });
+
+    // Component should have re-rendered even though state reference didn't change
+    expect(renderCount).toBeGreaterThan(rendersAfterMount);
+    expect(screen.getByTestId('count').textContent).toBe('1');
+  });
+
+  describe('async subscription', () => {
+    function defer<T = void>() {
+      let resolve!: (value: T) => void;
+      let reject!: (reason?: unknown) => void;
+      const promise = new Promise<T>((res, rej) => {
+        resolve = res;
+        reject = rej;
+      });
+      return { promise, resolve, reject };
+    }
+
+    type Deferred = ReturnType<typeof defer<void>>;
+
+    interface AsyncState {
+      value: string;
+    }
+
+    class AsyncVM extends ViewModel<AsyncState> {
+      private _deferred: Deferred | null = null;
+      get deferred() { return this._deferred; }
+
+      async load(): Promise<void> {
+        this._deferred = defer();
+        return this._deferred.promise;
+      }
+    }
+
+    function AsyncDisplay({ vm }: { vm: AsyncVM }) {
+      useInstance(vm);
+      const { loading, error } = vm.async.load;
+      return (
+        <div>
+          <span data-testid="loading">{String(loading)}</span>
+          <span data-testid="error">{error ?? 'none'}</span>
+        </div>
+      );
+    }
+
+    it('shows initial async state { loading: false, error: null }', () => {
+      const vm = new AsyncVM({ value: '' });
+      vm.init();
+
+      render(<AsyncDisplay vm={vm} />);
+      expect(screen.getByTestId('loading').textContent).toBe('false');
+      expect(screen.getByTestId('error').textContent).toBe('none');
+    });
+
+    it('re-renders when loading starts', async () => {
+      const vm = new AsyncVM({ value: '' });
+      vm.init();
+
+      render(<AsyncDisplay vm={vm} />);
+
+      await act(async () => {
+        vm.load();
+      });
+
+      expect(screen.getByTestId('loading').textContent).toBe('true');
+      expect(screen.getByTestId('error').textContent).toBe('none');
+
+      await act(async () => {
+        vm.deferred!.resolve();
+      });
+    });
+
+    it('re-renders when loading completes', async () => {
+      const vm = new AsyncVM({ value: '' });
+      vm.init();
+
+      render(<AsyncDisplay vm={vm} />);
+
+      let d: Deferred;
+      await act(async () => {
+        vm.load();
+        d = vm.deferred!;
+      });
+
+      expect(screen.getByTestId('loading').textContent).toBe('true');
+
+      await act(async () => {
+        d.resolve();
+      });
+
+      expect(screen.getByTestId('loading').textContent).toBe('false');
+    });
+
+    it('re-renders on async error', async () => {
+      class FailVM extends ViewModel<AsyncState> {
+        async load(): Promise<void> {
+          throw new Error('Network failed');
+        }
+      }
+
+      function FailDisplay({ vm }: { vm: FailVM }) {
+        useInstance(vm);
+        const { loading, error } = vm.async.load;
+        return (
+          <div>
+            <span data-testid="loading">{String(loading)}</span>
+            <span data-testid="error">{error ?? 'none'}</span>
+          </div>
+        );
+      }
+
+      const vm = new FailVM({ value: '' });
+      vm.init();
+
+      render(<FailDisplay vm={vm} />);
+
+      await act(async () => {
+        await vm.load().catch(() => {});
+      });
+
+      expect(screen.getByTestId('loading').textContent).toBe('false');
+      expect(screen.getByTestId('error').textContent).toBe('Network failed');
+    });
+
+    it('does not affect non-ViewModel subscribables', () => {
+      // Collection has no subscribeAsync — should work normally
+      const collection = new Collection<{ id: string; text: string }>([
+        { id: '1', text: 'Test' },
+      ]);
+
+      function CollectionDisplay({ col }: { col: Collection<{ id: string; text: string }> }) {
+        const items = useInstance(col);
+        return <div data-testid="count">{items.length}</div>;
+      }
+
+      render(<CollectionDisplay col={collection} />);
+      expect(screen.getByTestId('count').textContent).toBe('1');
+
+      act(() => {
+        collection.add({ id: '2', text: 'Another' });
+      });
+
+      expect(screen.getByTestId('count').textContent).toBe('2');
+    });
+
+    it('cleans up async subscription on unmount', async () => {
+      class SaveVM extends ViewModel<AsyncState> {
+        async save(): Promise<void> {
+          await Promise.resolve();
+        }
+      }
+
+      function SaveDisplay({ vm }: { vm: SaveVM }) {
+        useInstance(vm);
+        return <div data-testid="ok">ok</div>;
+      }
+
+      const vm = new SaveVM({ value: '' });
+      vm.init();
+
+      const { unmount } = render(<SaveDisplay vm={vm} />);
+      unmount();
+
+      // Should not throw after unmount
+      await act(async () => {
+        await vm.save();
+      });
+    });
+  });
+});

package/src/react/use-instance.ts

@@ -0,0 +1,60 @@
+import { useSyncExternalStore, useRef } from 'react';
+import type { Subscribable } from '../types';
+
+function hasAsyncSubscription(obj: unknown): obj is { subscribeAsync(cb: () => void): () => void } {
+  return (
+    obj !== null &&
+    typeof obj === 'object' &&
+    typeof (obj as any).subscribeAsync === 'function'
+  );
+}
+
+const SERVER_SNAPSHOT = () => 0;
+
+interface InstanceRef<S> {
+  version: number;
+  subscribable: Subscribable<S>;
+  subscribe: (onStoreChange: () => void) => () => void;
+  getSnapshot: () => number;
+}
+
+/**
+ * Subscribe to an existing Subscribable instance.
+ * No ownership - caller manages the instance lifecycle.
+ *
+ * If the instance has a `subscribeAsync` method (duck-typed),
+ * a combined subscription ensures async state changes also
+ * trigger React re-renders.
+ */
+export function useInstance<S>(subscribable: Subscribable<S>): S {
+  const ref = useRef<InstanceRef<S> | null>(null);
+
+  if (!ref.current || ref.current.subscribable !== subscribable) {
+    const version = { current: ref.current?.version ?? 0 };
+    ref.current = {
+      version: version.current,
+      subscribable,
+      subscribe: (onStoreChange: () => void) => {
+        const unsub1 = subscribable.subscribe(() => {
+          version.current++;
+          ref.current!.version = version.current;
+          onStoreChange();
+        });
+        let unsub2: (() => void) | undefined;
+        if (hasAsyncSubscription(subscribable)) {
+          unsub2 = subscribable.subscribeAsync(() => {
+            version.current++;
+            ref.current!.version = version.current;
+            onStoreChange();
+          });
+        }
+        return () => { unsub1(); unsub2?.(); };
+      },
+      getSnapshot: () => version.current,
+    };
+  }
+
+  useSyncExternalStore(ref.current.subscribe, ref.current.getSnapshot, SERVER_SNAPSHOT);
+
+  return subscribable.state;
+}