mvc-kit 2.12.0 → 2.12.1

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

@@ -0,0 +1,394 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { render, screen, act } from '@testing-library/react';
+import { vi } from 'vitest';
+import { Model } from '../Model';
+import type { ValidationErrors } from '../types';
+import { useModel, useModelRef, useField } from './use-model';
+
+interface FormState {
+  name: string;
+  email: string;
+  age: number;
+}
+
+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';
+    if (state.age < 0) errors.age = 'Age must be positive';
+    return errors;
+  }
+
+  setName(name: string) {
+    this.set({ name });
+  }
+
+  setEmail(email: string) {
+    this.set({ email });
+  }
+
+  setAge(age: number) {
+    this.set({ age });
+  }
+}
+
+// Model with public set for useField testing
+class PublicFormModel extends Model<FormState> {
+  protected validate(state: FormState): ValidationErrors<FormState> {
+    const errors: ValidationErrors<FormState> = {};
+    if (!state.name) errors.name = 'Name is required';
+    return errors;
+  }
+
+  // Expose set as public for useField
+  public set(partial: Partial<FormState>) {
+    super.set(partial);
+  }
+}
+
+function FormComponent() {
+  const { state, errors, valid, dirty, model } = useModel(
+    () => new FormModel({ name: '', email: '', age: 0 })
+  );
+
+  return (
+    <div>
+      <div data-testid="name">{state.name}</div>
+      <div data-testid="email">{state.email}</div>
+      <div data-testid="valid">{valid ? 'valid' : 'invalid'}</div>
+      <div data-testid="dirty">{dirty ? 'dirty' : 'clean'}</div>
+      <div data-testid="name-error">{errors.name || ''}</div>
+      <button onClick={() => model.setName('John')}>Set Name</button>
+    </div>
+  );
+}
+
+describe('useModel', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('should return state and validation', () => {
+    render(<FormComponent />);
+
+    expect(screen.getByTestId('name').textContent).toBe('');
+    expect(screen.getByTestId('valid').textContent).toBe('invalid');
+    expect(screen.getByTestId('name-error').textContent).toBe('Name is required');
+  });
+
+  it('should track dirty state', () => {
+    render(<FormComponent />);
+
+    expect(screen.getByTestId('dirty').textContent).toBe('clean');
+
+    act(() => {
+      screen.getByRole('button').click();
+    });
+
+    expect(screen.getByTestId('dirty').textContent).toBe('dirty');
+    expect(screen.getByTestId('name').textContent).toBe('John');
+  });
+
+  it('should update validation on state change', () => {
+    render(<FormComponent />);
+
+    expect(screen.getByTestId('name-error').textContent).toBe('Name is required');
+
+    act(() => {
+      screen.getByRole('button').click();
+    });
+
+    expect(screen.getByTestId('name-error').textContent).toBe('');
+  });
+
+  it('should dispose on unmount', () => {
+    let disposed = false;
+    class TrackingModel extends Model<FormState> {
+      protected onDispose() {
+        disposed = true;
+      }
+      setName(name: string) {
+        this.set({ name });
+      }
+    }
+
+    function Tracked() {
+      useModel(() => new TrackingModel({ name: '', email: '', age: 0 }));
+      return null;
+    }
+
+    const { unmount } = render(<Tracked />);
+    expect(disposed).toBe(false);
+
+    unmount();
+    vi.runAllTimers();
+    expect(disposed).toBe(true);
+  });
+
+  describe('init lifecycle', () => {
+    it('should auto-call init on mount', () => {
+      let initCalled = false;
+      class InitModel extends Model<FormState> {
+        protected onInit() {
+          initCalled = true;
+        }
+        setName(name: string) { this.set({ name }); }
+      }
+
+      function Comp() {
+        useModel(() => new InitModel({ name: '', email: '', age: 0 }));
+        return null;
+      }
+
+      render(<Comp />);
+      expect(initCalled).toBe(true);
+    });
+
+    it('should call init only once across re-renders', () => {
+      let initCount = 0;
+      class InitModel extends Model<FormState> {
+        protected onInit() {
+          initCount++;
+        }
+        setName(name: string) { this.set({ name }); }
+      }
+
+      function Comp() {
+        const { state, model } = useModel(() => new InitModel({ name: '', email: '', age: 0 }));
+        return (
+          <div>
+            <div data-testid="name">{state.name}</div>
+            <button onClick={() => model.setName('test')}>Set</button>
+          </div>
+        );
+      }
+
+      render(<Comp />);
+      expect(initCount).toBe(1);
+
+      act(() => {
+        screen.getByRole('button').click();
+      });
+      expect(initCount).toBe(1);
+    });
+  });
+});
+
+describe('useModelRef', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('should return the model instance', () => {
+    let capturedModel: PublicFormModel | null = null;
+    function Comp() {
+      capturedModel = useModelRef(() => new PublicFormModel({ name: 'John', email: 'j@test.com', age: 30 }));
+      return null;
+    }
+
+    render(<Comp />);
+    expect(capturedModel).toBeInstanceOf(PublicFormModel);
+    expect(capturedModel!.state.name).toBe('John');
+  });
+
+  it('should auto-call init on mount', () => {
+    let initCalled = false;
+    class InitModel extends Model<FormState> {
+      protected onInit() { initCalled = true; }
+    }
+
+    function Comp() {
+      useModelRef(() => new InitModel({ name: '', email: '', age: 0 }));
+      return null;
+    }
+
+    render(<Comp />);
+    expect(initCalled).toBe(true);
+  });
+
+  it('should dispose on unmount', () => {
+    let disposed = false;
+    class TrackingModel extends Model<FormState> {
+      protected onDispose() { disposed = true; }
+    }
+
+    function Comp() {
+      useModelRef(() => new TrackingModel({ name: '', email: '', age: 0 }));
+      return null;
+    }
+
+    const { unmount } = render(<Comp />);
+    expect(disposed).toBe(false);
+
+    unmount();
+    vi.runAllTimers();
+    expect(disposed).toBe(true);
+  });
+
+  it('should not re-render parent when model state changes', () => {
+    let parentRenderCount = 0;
+    let capturedModel: PublicFormModel | null = null;
+
+    function Parent() {
+      parentRenderCount++;
+      capturedModel = useModelRef(() => new PublicFormModel({ name: '', email: 'test@test.com', age: 25 }));
+      return <div data-testid="parent">rendered</div>;
+    }
+
+    render(<Parent />);
+    const rendersAfterMount = parentRenderCount;
+
+    act(() => {
+      capturedModel!.set({ name: 'Jane' });
+    });
+
+    // Parent should NOT have re-rendered
+    expect(parentRenderCount).toBe(rendersAfterMount);
+  });
+
+  it('should return stable model across re-renders', () => {
+    const models: PublicFormModel[] = [];
+
+    function Comp({ label }: { label: string }) {
+      const model = useModelRef(() => new PublicFormModel({ name: '', email: '', age: 0 }));
+      models.push(model);
+      return <div>{label}</div>;
+    }
+
+    const { rerender } = render(<Comp label="a" />);
+    rerender(<Comp label="b" />);
+    rerender(<Comp label="c" />);
+
+    expect(models[0]).toBe(models[1]);
+    expect(models[1]).toBe(models[2]);
+  });
+
+  it('works with useField for per-field isolation', () => {
+    let parentRenderCount = 0;
+    let fieldRenderCount = 0;
+
+    function NameField({ model }: { model: PublicFormModel }) {
+      fieldRenderCount++;
+      const { value, set } = useField(model, 'name');
+      return (
+        <div>
+          <div data-testid="field-value">{value}</div>
+          <button data-testid="set-name" onClick={() => set('Jane')}>Set</button>
+        </div>
+      );
+    }
+
+    function Parent() {
+      parentRenderCount++;
+      const model = useModelRef(() => new PublicFormModel({ name: '', email: 'test@test.com', age: 25 }));
+      return <NameField model={model} />;
+    }
+
+    render(<Parent />);
+    const parentRendersAfterMount = parentRenderCount;
+    const fieldRendersAfterMount = fieldRenderCount;
+
+    act(() => {
+      screen.getByTestId('set-name').click();
+    });
+
+    // Field should have re-rendered
+    expect(fieldRenderCount).toBeGreaterThan(fieldRendersAfterMount);
+    expect(screen.getByTestId('field-value').textContent).toBe('Jane');
+
+    // Parent should NOT have re-rendered
+    expect(parentRenderCount).toBe(parentRendersAfterMount);
+  });
+});
+
+describe('useField', () => {
+  function FieldComponent({ model }: { model: PublicFormModel }) {
+    const { value, error, set } = useField(model, 'name');
+
+    return (
+      <div>
+        <div data-testid="value">{value}</div>
+        <div data-testid="error">{error || ''}</div>
+        <button onClick={() => set('Jane')}>Set</button>
+      </div>
+    );
+  }
+
+  it('should return field value and error', () => {
+    const model = new PublicFormModel({ name: '', email: 'test@test.com', age: 25 });
+    render(<FieldComponent model={model} />);
+
+    expect(screen.getByTestId('value').textContent).toBe('');
+    expect(screen.getByTestId('error').textContent).toBe('Name is required');
+  });
+
+  it('should update field value', () => {
+    const model = new PublicFormModel({ name: '', email: 'test@test.com', age: 25 });
+    render(<FieldComponent model={model} />);
+
+    act(() => {
+      screen.getByRole('button').click();
+    });
+
+    expect(screen.getByTestId('value').textContent).toBe('Jane');
+    expect(screen.getByTestId('error').textContent).toBe('');
+  });
+
+  it('should only re-render when field changes', () => {
+    const model = new PublicFormModel({ name: 'John', email: 'test@test.com', age: 25 });
+    let renderCount = 0;
+
+    function TrackedField({ model }: { model: PublicFormModel }) {
+      renderCount++;
+      const { value } = useField(model, 'name');
+      return <div data-testid="value">{value}</div>;
+    }
+
+    render(<TrackedField model={model} />);
+    expect(renderCount).toBe(1);
+
+    // Change a different field - should not re-render
+    act(() => {
+      model.set({ email: 'new@test.com' });
+    });
+
+    // renderCount might still be 1 or could be 2 depending on React
+    // The important thing is that the value hasn't changed
+    expect(screen.getByTestId('value').textContent).toBe('John');
+  });
+});
+
+describe('type-level: useField rejects invalid field names', () => {
+  it('rejects invalid field key via @ts-expect-error', () => {
+    const model = new PublicFormModel({ name: '', email: '', age: 0 });
+
+    // Compile-time only — runtime call would fail, we just check the type error
+    const _useField = (() => ({})) as unknown as typeof useField;
+
+    // @ts-expect-error - 'invalidField' is not a key of FormState
+    _useField(model, 'invalidField');
+  });
+
+  it('accepts valid field key without error', () => {
+    const model = new PublicFormModel({ name: '', email: '', age: 0 });
+    const _useField = (() => ({})) as unknown as typeof useField;
+
+    // These should NOT produce type errors — Model<S> has concrete S-typed
+    // properties (state, committed, errors) that anchor inference of S,
+    // preventing TypeScript from widening S to satisfy an invalid key.
+    _useField(model, 'name');
+    _useField(model, 'email');
+    _useField(model, 'age');
+  });
+});

package/src/react/use-model.ts

@@ -0,0 +1,161 @@
+import { useRef, useEffect, useSyncExternalStore, useCallback } from 'react';
+import type { Model } from '../Model';
+import type { ValidationErrors } from '../types';
+import type { StateOf } from './types';
+import { isInitializable } from './guards';
+
+/** Return type of `useModel`, providing state, validation, and model access. */
+export interface ModelHandle<S extends object, M extends Model<S>> {
+  state: S;
+  errors: ValidationErrors<S>;
+  valid: boolean;
+  dirty: boolean;
+  model: M;
+}
+
+/**
+ * Bind to a component-scoped Model with validation and dirty state exposed.
+ */
+export function useModel<M extends Model<any>>(
+  factory: () => M
+): ModelHandle<StateOf<M>, M> {
+  const modelRef = useRef<M | null>(null);
+  const mountedRef = useRef(false);
+
+  if (!modelRef.current || modelRef.current.disposed) {
+    modelRef.current = factory();
+  }
+
+  const modelSubscribe = useCallback(
+    (onStoreChange: () => void) => modelRef.current!.subscribe(onStoreChange),
+    []
+  );
+  const modelSnapshot = useCallback(
+    () => modelRef.current!.state,
+    []
+  );
+  useSyncExternalStore(modelSubscribe, modelSnapshot, modelSnapshot);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    if (isInitializable(modelRef.current)) {
+      modelRef.current.init();
+    }
+    return () => {
+      mountedRef.current = false;
+      setTimeout(() => {
+        if (!mountedRef.current) {
+          modelRef.current?.dispose();
+        }
+      }, 0);
+    };
+  }, []);
+
+  const model = modelRef.current;
+
+  return {
+    state: model.state,
+    errors: model.errors,
+    valid: model.valid,
+    dirty: model.dirty,
+    model,
+  };
+}
+
+/**
+ * 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`.
+ */
+export function useModelRef<M extends Model<any>>(factory: () => M): M {
+  const modelRef = useRef<M | null>(null);
+  const mountedRef = useRef(false);
+
+  if (!modelRef.current || modelRef.current.disposed) {
+    modelRef.current = factory();
+  }
+
+  useEffect(() => {
+    mountedRef.current = true;
+    if (isInitializable(modelRef.current)) {
+      modelRef.current.init();
+    }
+    return () => {
+      mountedRef.current = false;
+      setTimeout(() => {
+        if (!mountedRef.current) {
+          modelRef.current?.dispose();
+        }
+      }, 0);
+    };
+  }, []);
+
+  return modelRef.current;
+}
+
+/** Return type of `useField`, providing a single field's value, error, and setter. */
+export interface FieldHandle<V> {
+  value: V;
+  error: string | undefined;
+  set: (value: V) => void;
+}
+
+/**
+ * Bind to a single Model field with surgical re-renders.
+ */
+export function useField<S extends object, K extends keyof S>(
+  model: Model<S>,
+  field: K
+): FieldHandle<S[K]> {
+  // Track the field value and error for comparison
+  const getSnapshot = useCallback(() => {
+    return {
+      value: model.state[field],
+      error: model.errors[field],
+    };
+  }, [model, field]);
+
+  // Use object comparison for subscription
+  const cachedRef = useRef(getSnapshot());
+
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      return model.subscribe(() => {
+        const next = getSnapshot();
+        const current = cachedRef.current;
+
+        // Only trigger re-render if field value or error changed
+        if (next.value !== current.value || next.error !== current.error) {
+          cachedRef.current = next;
+          onStoreChange();
+        }
+      });
+    },
+    [model, getSnapshot]
+  );
+
+  const snapshot = useSyncExternalStore(
+    subscribe,
+    () => cachedRef.current,
+    () => cachedRef.current
+  );
+
+  const set = useCallback(
+    (value: S[K]) => {
+      // Access the protected set method through type assertion
+      // The Model subclass should expose a setter method
+      const partial: Partial<S> = { [field]: value } as unknown as Partial<S>;
+      (model as unknown as { set: (partial: Partial<S>) => void }).set(partial);
+    },
+    [model, field]
+  );
+
+  return {
+    value: snapshot.value,
+    error: snapshot.error,
+    set,
+  };
+}