mvc-kit 2.12.0 → 2.12.2

package/src/react/strict-mode.test.tsx

@@ -0,0 +1,266 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { StrictMode } from 'react';
+import { render, screen, act } from '@testing-library/react';
+import { ViewModel } from '../ViewModel';
+import { Model } from '../Model';
+import { Collection } from '../Collection';
+import { Controller } from '../Controller';
+import { useLocal } from './use-local';
+import { useModel } from './use-model';
+import type { ValidationErrors } from '../types';
+
+// ── Test classes ──
+
+interface CounterState {
+  count: number;
+}
+
+class CounterVM extends ViewModel<CounterState> {
+  constructor() {
+    super({ count: 0 });
+  }
+
+  increment() {
+    this.set((prev) => ({ count: prev.count + 1 }));
+  }
+}
+
+interface Todo {
+  id: string;
+  text: string;
+  done: boolean;
+}
+
+class TodoCollection extends Collection<Todo> {}
+
+class TestController extends Controller {
+  greet(): string {
+    return 'hello';
+  }
+}
+
+interface FormState {
+  name: string;
+  email: string;
+}
+
+class FormModel extends Model<FormState> {
+  setName(name: string) {
+    this.set({ name });
+  }
+
+  setEmail(email: string) {
+    this.set({ email });
+  }
+
+  protected validate(state: FormState): ValidationErrors<FormState> {
+    const errors: ValidationErrors<FormState> = {};
+    if (!state.name) errors.name = 'Required';
+    if (!state.email.includes('@')) errors.email = 'Invalid email';
+    return errors;
+  }
+}
+
+// ── Tests ──
+
+describe('React StrictMode compatibility', () => {
+  it('useLocal + ViewModel renders and supports interaction', () => {
+    function Counter() {
+      const [state, vm] = useLocal(CounterVM);
+      return (
+        <div>
+          <span data-testid="count">{state.count}</span>
+          <button onClick={() => vm.increment()}>+</button>
+        </div>
+      );
+    }
+
+    render(
+      <StrictMode>
+        <Counter />
+      </StrictMode>
+    );
+
+    expect(screen.getByTestId('count').textContent).toBe('0');
+
+    act(() => {
+      screen.getByRole('button').click();
+    });
+
+    expect(screen.getByTestId('count').textContent).toBe('1');
+  });
+
+  it('useLocal + Collection renders and supports interaction', () => {
+    function TodoList() {
+      const [items, collection] = useLocal(TodoCollection);
+      return (
+        <div>
+          <span data-testid="count">{items.length}</span>
+          <button onClick={() => collection.add({ id: String(items.length + 1), text: 'New', done: false })}>
+            Add
+          </button>
+        </div>
+      );
+    }
+
+    render(
+      <StrictMode>
+        <TodoList />
+      </StrictMode>
+    );
+
+    expect(screen.getByTestId('count').textContent).toBe('0');
+
+    act(() => {
+      screen.getByRole('button').click();
+    });
+
+    expect(screen.getByTestId('count').textContent).toBe('1');
+  });
+
+  it('useLocal + Controller (Disposable-only) renders without crash', () => {
+    function Greeter() {
+      const ctrl = useLocal(TestController);
+      return <span data-testid="greeting">{ctrl.greet()}</span>;
+    }
+
+    render(
+      <StrictMode>
+        <Greeter />
+      </StrictMode>
+    );
+
+    expect(screen.getByTestId('greeting').textContent).toBe('hello');
+  });
+
+  it('useModel renders and supports interaction', () => {
+    function Form() {
+      const { state, errors, valid, model } = useModel(() => new FormModel({ name: '', email: '' }));
+      return (
+        <div>
+          <span data-testid="name">{state.name}</span>
+          <span data-testid="valid">{String(valid)}</span>
+          <span data-testid="name-error">{errors.name ?? ''}</span>
+          <button onClick={() => model.setName('Alice')}>Set Name</button>
+        </div>
+      );
+    }
+
+    render(
+      <StrictMode>
+        <Form />
+      </StrictMode>
+    );
+
+    expect(screen.getByTestId('name').textContent).toBe('');
+    expect(screen.getByTestId('valid').textContent).toBe('false');
+
+    act(() => {
+      screen.getByRole('button').click();
+    });
+
+    expect(screen.getByTestId('name').textContent).toBe('Alice');
+    expect(screen.getByTestId('name-error').textContent).toBe('');
+  });
+
+  it('useLocal + ViewModel: onInit called exactly once in StrictMode', () => {
+    let initCount = 0;
+
+    class InitCounterVM extends ViewModel<CounterState> {
+      constructor() {
+        super({ count: 0 });
+      }
+      protected onInit() {
+        initCount++;
+      }
+      increment() {
+        this.set((prev) => ({ count: prev.count + 1 }));
+      }
+    }
+
+    function Counter() {
+      const [state] = useLocal(InitCounterVM);
+      return <span data-testid="init-count">{state.count}</span>;
+    }
+
+    render(
+      <StrictMode>
+        <Counter />
+      </StrictMode>
+    );
+
+    expect(initCount).toBe(1);
+  });
+
+  it('useModel: onInit called exactly once in StrictMode', () => {
+    let initCount = 0;
+
+    class InitFormModel extends Model<FormState> {
+      protected onInit() {
+        initCount++;
+      }
+      setName(name: string) {
+        this.set({ name });
+      }
+      setEmail(email: string) {
+        this.set({ email });
+      }
+    }
+
+    function Form() {
+      const { state } = useModel(() => new InitFormModel({ name: '', email: '' }));
+      return <span data-testid="init-name">{state.name}</span>;
+    }
+
+    render(
+      <StrictMode>
+        <Form />
+      </StrictMode>
+    );
+
+    expect(initCount).toBe(1);
+  });
+
+  it('useLocal + ViewModel: signal not aborted during StrictMode fake unmount cycle', () => {
+    let capturedSignal: AbortSignal | null = null;
+
+    class SignalVM extends ViewModel<CounterState> {
+      constructor() {
+        super({ count: 0 });
+      }
+      getSignal() {
+        capturedSignal = this.disposeSignal;
+        return this.disposeSignal;
+      }
+    }
+
+    function SignalComponent() {
+      const [state, vm] = useLocal(SignalVM);
+      vm.getSignal();
+      return <span data-testid="signal-count">{state.count}</span>;
+    }
+
+    const { unmount } = render(
+      <StrictMode>
+        <SignalComponent />
+      </StrictMode>
+    );
+
+    // After StrictMode mount/unmount/remount cycle, signal should NOT be aborted
+    expect(capturedSignal).not.toBeNull();
+    expect(capturedSignal!.aborted).toBe(false);
+
+    // On real unmount, signal IS aborted
+    unmount();
+
+    // Need to wait for the deferred disposal timeout
+    return new Promise<void>((resolve) => {
+      setTimeout(() => {
+        expect(capturedSignal!.aborted).toBe(true);
+        resolve();
+      }, 10);
+    });
+  });
+});

package/src/react/types.ts

@@ -0,0 +1,25 @@
+import type { Subscribable, Disposable } from '../types';
+
+/**
+ * Extract state type from a Subscribable.
+ */
+export type StateOf<T> = T extends Subscribable<infer S> ? S : never;
+
+/**
+ * Extract item type from a Collection.
+ */
+export type ItemOf<T> = T extends Subscribable<(infer I)[]> ? I : never;
+
+/**
+ * Constructor type for singleton classes.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type SingletonClass<T extends Disposable, Args extends unknown[] = any[]> = new (
+  ...args: Args
+) => T;
+
+/**
+ * Provider registry mapping classes to instances.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ProviderRegistry = Map<new (...args: any[]) => any, any>;

package/src/react/use-event-bus.md

@@ -0,0 +1,214 @@
+# useEvent & useEmit
+
+React hooks for subscribing to and emitting typed events from an [EventBus](../EventBus.md) or [ViewModel](../ViewModel.md).
+
+---
+
+## useEvent
+
+Subscribe to a typed event with automatic cleanup on unmount.
+
+### Signature
+
+```typescript
+function useEvent<E extends Record<string, any>, K extends keyof E>(
+  source: EventBus<E> | { events: EventBus<E> },
+  event: K,
+  handler: (payload: E[K]) => void
+): void
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|---|---|---|
+| `source` | `EventBus<E>` or `{ events: EventBus<E> }` | An EventBus instance directly, or any object with an `events` property (e.g. a ViewModel). |
+| `event` | `K extends keyof E` | The event name to subscribe to. Type-checked against the event map. |
+| `handler` | `(payload: E[K]) => void` | Callback invoked when the event fires. Payload type is inferred from the event map. |
+
+### Behavior
+
+- Calls `bus.on(event, handler)` inside a `useEffect` and returns the unsubscribe function as cleanup.
+- The handler is stored in a ref (`useRef`) and updated on every render, so the callback always closes over the latest component state — no stale closures, no need for `useCallback`.
+- The effect re-runs only when the `bus` instance or `event` name changes (not on handler changes).
+- On unmount, the subscription is removed automatically.
+
+### With a Standalone EventBus
+
+```tsx
+import { useEvent } from 'mvc-kit/react';
+
+interface AppEvents {
+  'item:created': { id: string; name: string };
+  'auth:logout': undefined;
+}
+
+function Notifications({ bus }: { bus: EventBus<AppEvents> }) {
+  useEvent(bus, 'item:created', ({ name }) => {
+    toast.success(`${name} created`);
+  });
+
+  return null;
+}
+```
+
+### With a ViewModel
+
+ViewModels expose their internal EventBus via an `events` getter. `useEvent` detects this automatically — pass the ViewModel directly as the source.
+
+```tsx
+interface Events {
+  saved: { id: string };
+  validationFailed: undefined;
+}
+
+class ItemViewModel extends ViewModel<State, Events> {
+  async save() {
+    const result = await this.service.save(this.state.draft, this.disposeSignal);
+    this.emit('saved', { id: result.id });
+  }
+}
+
+function ItemPage() {
+  const [state, vm] = useLocal(ItemViewModel, { draft: null });
+
+  useEvent(vm, 'saved', ({ id }) => {
+    toast.success(`Saved ${id}`);
+    navigate(`/items/${id}`);
+  });
+
+  return <div>{/* ... */}</div>;
+}
+```
+
+Key detail: `emit()` on a ViewModel is **protected** — only the ViewModel can emit. Components can only subscribe.
+
+### Multiple Events
+
+Call `useEvent` once per event type. Each subscription is independent:
+
+```tsx
+function ItemPage() {
+  const [state, vm] = useLocal(ItemViewModel, { /* ... */ });
+
+  useEvent(vm, 'saved', ({ id }) => {
+    toast.success(`Item ${id} saved`);
+  });
+
+  useEvent(vm, 'validationFailed', () => {
+    scrollToFirstError();
+  });
+
+  return <div>{/* ... */}</div>;
+}
+```
+
+### Unmount Safety
+
+When the component unmounts, the subscription is cleaned up. Emitting after unmount does not throw — the handler simply isn't called.
+
+```tsx
+const { unmount } = render(<Listener bus={bus} />);
+unmount();
+bus.emit('increment', { amount: 1 }); // safe, no error
+```
+
+---
+
+## useEmit
+
+Returns a stable `emit` function bound to an EventBus. Useful in components that only emit events (no subscription needed).
+
+### Signature
+
+```typescript
+function useEmit<E extends Record<string, any>>(
+  bus: EventBus<E>
+): <K extends keyof E>(event: K, payload: E[K]) => void
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|---|---|---|
+| `bus` | `EventBus<E>` | The EventBus to emit on. |
+
+### Behavior
+
+- Wraps `bus.emit` in a `useCallback` memoized on the `bus` reference.
+- The returned function is referentially stable across re-renders as long as the bus instance doesn't change.
+- Fully type-safe — event names and payloads are checked against the event map.
+
+### Usage
+
+```tsx
+import { useEmit } from 'mvc-kit/react';
+
+function ActionBar({ bus }: { bus: EventBus<AppEvents> }) {
+  const emit = useEmit(bus);
+
+  return (
+    <div>
+      <button onClick={() => emit('increment', { amount: 1 })}>+1</button>
+      <button onClick={() => emit('increment', { amount: 5 })}>+5</button>
+      <button onClick={() => emit('auth:logout', undefined)}>Log Out</button>
+    </div>
+  );
+}
+```
+
+### Emitter + Listener Pattern
+
+`useEmit` and `useEvent` compose naturally when sibling components communicate through a shared bus:
+
+```tsx
+function App() {
+  const bus = useMemo(() => new EventBus<AppEvents>(), []);
+
+  return (
+    <>
+      <EventEmitter bus={bus} />
+      <EventListener bus={bus} />
+    </>
+  );
+}
+```
+
+---
+
+## When to Use Which Source
+
+| Scenario | Source | Hook |
+|---|---|---|
+| ViewModel emits one-shot signals (saved, deleted, validation) | ViewModel instance | `useEvent(vm, ...)` |
+| App-wide broadcasts (logout, data loaded on another route) | Singleton EventBus | `useEvent(bus, ...)` |
+| Component only needs to emit, not subscribe | Singleton EventBus | `useEmit(bus)` |
+
+---
+
+## Best Practices
+
+**Use `useEvent` for imperative one-shot signals, not data synchronization.** Toasts, redirects, scroll-to-error, and animations are good fits. For reactive data, use `useLocal` / `useSingleton` with ViewModel state and getters.
+
+**Prefer ViewModel events over standalone EventBus for component-scoped signals.** The ViewModel's internal bus is lazy, auto-disposed, and type-safe via the second generic parameter. Only use a standalone singleton EventBus for cross-route or app-wide broadcasts.
+
+**No `useCallback` needed for handlers.** The handler ref pattern inside `useEvent` ensures the latest closure is always called without creating a new subscription on every render.
+
+**Pass `undefined` for events with no payload.** The event map uses `undefined` (not `void`) for empty payloads:
+
+```typescript
+interface Events {
+  reset: undefined;
+}
+
+bus.emit('reset', undefined);
+```
+
+**Don't use `useEvent` for Collection changes.** Collections carry state; EventBus carries intent. Subscribe to collections inside the ViewModel via `subscribeTo`, not in the component.
+
+---
+
+## Related
+
+- [EventBus](../EventBus.md) — the underlying pub/sub primitive
+- [ViewModel](../ViewModel.md) — built-in events via second generic parameter

package/src/react/use-event-bus.test.tsx

@@ -0,0 +1,168 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { render, screen, act } from '@testing-library/react';
+import { useState } from 'react';
+import { EventBus } from '../EventBus';
+import { ViewModel } from '../ViewModel';
+import { useEvent, useEmit } from './use-event-bus';
+
+interface AppEvents {
+  increment: { amount: number };
+  reset: undefined;
+}
+
+function EventListener({ bus }: { bus: EventBus<AppEvents> }) {
+  const [count, setCount] = useState(0);
+
+  useEvent(bus, 'increment', (payload) => {
+    setCount((c) => c + payload.amount);
+  });
+
+  useEvent(bus, 'reset', () => {
+    setCount(0);
+  });
+
+  return <div data-testid="count">{count}</div>;
+}
+
+function EventEmitter({ bus }: { bus: EventBus<AppEvents> }) {
+  const emit = useEmit(bus);
+
+  return (
+    <div>
+      <button onClick={() => emit('increment', { amount: 1 })}>+1</button>
+      <button onClick={() => emit('increment', { amount: 5 })}>+5</button>
+      <button onClick={() => emit('reset', undefined)}>Reset</button>
+    </div>
+  );
+}
+
+describe('useEvent', () => {
+  it('should subscribe to events', () => {
+    const bus = new EventBus<AppEvents>();
+
+    render(<EventListener bus={bus} />);
+    expect(screen.getByTestId('count').textContent).toBe('0');
+
+    act(() => {
+      bus.emit('increment', { amount: 10 });
+    });
+
+    expect(screen.getByTestId('count').textContent).toBe('10');
+  });
+
+  it('should handle multiple event types', () => {
+    const bus = new EventBus<AppEvents>();
+
+    render(<EventListener bus={bus} />);
+
+    act(() => {
+      bus.emit('increment', { amount: 5 });
+    });
+    expect(screen.getByTestId('count').textContent).toBe('5');
+
+    act(() => {
+      bus.emit('reset', undefined);
+    });
+    expect(screen.getByTestId('count').textContent).toBe('0');
+  });
+
+  it('should unsubscribe on unmount', () => {
+    const bus = new EventBus<AppEvents>();
+    const { unmount } = render(<EventListener bus={bus} />);
+
+    act(() => {
+      bus.emit('increment', { amount: 1 });
+    });
+    expect(screen.getByTestId('count').textContent).toBe('1');
+
+    unmount();
+
+    // This should not throw even after unmount
+    expect(() => bus.emit('increment', { amount: 1 })).not.toThrow();
+  });
+});
+
+describe('useEmit', () => {
+  it('should return a stable emit function', () => {
+    const bus = new EventBus<AppEvents>();
+
+    function App() {
+      return (
+        <>
+          <EventListener bus={bus} />
+          <EventEmitter bus={bus} />
+        </>
+      );
+    }
+
+    render(<App />);
+
+    act(() => {
+      screen.getByRole('button', { name: '+1' }).click();
+    });
+    expect(screen.getByTestId('count').textContent).toBe('1');
+
+    act(() => {
+      screen.getByRole('button', { name: '+5' }).click();
+    });
+    expect(screen.getByTestId('count').textContent).toBe('6');
+
+    act(() => {
+      screen.getByRole('button', { name: 'Reset' }).click();
+    });
+    expect(screen.getByTestId('count').textContent).toBe('0');
+  });
+});
+
+describe('useEvent with ViewModel', () => {
+  interface VMEvents {
+    notify: { text: string };
+  }
+
+  class TestVM extends ViewModel<{ count: number }, VMEvents> {
+    fire(text: string) {
+      this.emit('notify', { text });
+    }
+  }
+
+  function VMListener({ vm }: { vm: TestVM }) {
+    const [message, setMessage] = useState('');
+
+    useEvent(vm, 'notify', (payload) => {
+      setMessage(payload.text);
+    });
+
+    return <div data-testid="message">{message}</div>;
+  }
+
+  it('subscribes to ViewModel events and fires handler', () => {
+    const vm = new TestVM({ count: 0 });
+
+    render(<VMListener vm={vm} />);
+    expect(screen.getByTestId('message').textContent).toBe('');
+
+    act(() => {
+      vm.fire('hello');
+    });
+
+    expect(screen.getByTestId('message').textContent).toBe('hello');
+  });
+
+  it('auto-unsubscribes on unmount', () => {
+    const vm = new TestVM({ count: 0 });
+
+    const { unmount } = render(<VMListener vm={vm} />);
+
+    act(() => {
+      vm.fire('first');
+    });
+    expect(screen.getByTestId('message').textContent).toBe('first');
+
+    unmount();
+
+    // Should not throw after unmount
+    expect(() => vm.fire('second')).not.toThrow();
+  });
+});

package/src/react/use-event-bus.ts

@@ -0,0 +1,40 @@
+import { useEffect, useCallback, useRef } from 'react';
+import { EventBus } from '../EventBus';
+
+/**
+ * Subscribe to a typed event, auto-unsubscribes on unmount.
+ * Accepts an EventBus directly or any object with an `events` property (e.g. a ViewModel).
+ */
+export function useEvent<E extends Record<string, any>, K extends keyof E>(
+  source: EventBus<E> | { events: EventBus<E> },
+  event: K,
+  handler: (payload: E[K]) => void
+): void {
+  const bus = source instanceof EventBus ? source : source.events;
+
+  // Use ref to keep handler stable across re-renders
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
+  useEffect(() => {
+    const unsubscribe = bus.on(event, (payload) => {
+      handlerRef.current(payload);
+    });
+
+    return unsubscribe;
+  }, [bus, event]);
+}
+
+/**
+ * Get a stable emit function for an EventBus.
+ */
+export function useEmit<E extends Record<string, any>>(
+  bus: EventBus<E>
+): <K extends keyof E>(event: K, payload: E[K]) => void {
+  return useCallback(
+    <K extends keyof E>(event: K, payload: E[K]) => {
+      bus.emit(event, payload);
+    },
+    [bus]
+  );
+}