mvc-kit 2.12.0 → 2.12.2

package/src/react/components/types.ts

@@ -0,0 +1,90 @@
+import type { ReactNode } from 'react';
+import type { SortDescriptor } from '../../Sorting';
+
+/** Props passed to a custom sort indicator render function. */
+export interface SortHeaderProps {
+  active: boolean;
+  direction: 'asc' | 'desc';
+  index: number;
+  onToggle: () => void;
+}
+
+/** Controlled selection state using callback props. */
+export interface SelectionState<K = string | number> {
+  selected: ReadonlySet<K>;
+  onToggle: (key: K) => void;
+  onToggleAll: (allKeys: K[]) => void;
+}
+
+/** Structural interface matching Selection<K> — duck-type for direct helper pass-through. */
+export interface SelectionHelper {
+  readonly selected: ReadonlySet<any>;
+  toggle(key: any): void;
+  toggleAll(allKeys: any[]): void;
+}
+
+/** Controlled pagination state using callback props. */
+export interface PaginationState {
+  page: number;
+  total: number;
+  onPageChange: (page: number) => void;
+}
+
+/** Structural interface matching Pagination — duck-type for direct helper pass-through. */
+export interface PaginationHelper {
+  readonly page: number;
+  readonly pageSize: number;
+  setPage(page: number): void;
+}
+
+/** Structural interface matching Sorting<T> — duck-type for direct helper pass-through. */
+export interface SortingHelper {
+  readonly sorts: readonly SortDescriptor[];
+  toggle(key: string): void;
+}
+
+/** Computed pagination info passed to renderPagination slots. */
+export interface PaginationInfo {
+  page: number;
+  pageCount: number;
+  total: number;
+  pageSize: number;
+  hasPrev: boolean;
+  hasNext: boolean;
+  goToPage: (p: number) => void;
+  goPrev: () => void;
+  goNext: () => void;
+}
+
+/** Loading and error state props for async-aware components. */
+export interface AsyncStateProps {
+  loading?: boolean;
+  error?: string | null;
+}
+
+/** Column definition for DataTable. */
+export interface Column<T> {
+  key: string;
+  header: ReactNode;
+  render: (item: T, index: number) => ReactNode;
+  sortable?: boolean;
+  width?: string;
+  align?: 'left' | 'center' | 'right';
+}
+
+// ── Detection functions (duck-type discriminators) ──
+
+/** @internal Detect whether a selection prop is a Selection helper instance. */
+export function isSelectionHelper(s: SelectionState | SelectionHelper): s is SelectionHelper {
+  return 'toggle' in s && !('onToggle' in s);
+}
+
+/** @internal Detect whether a pagination prop is a Pagination helper instance. */
+export function isPaginationHelper(p: PaginationState | PaginationHelper): p is PaginationHelper {
+  return 'setPage' in p && !('onPageChange' in p);
+}
+
+/** @internal Detect whether a sort prop is a Sorting helper instance. */
+export function isSortingHelper(s: readonly SortDescriptor[] | SortingHelper): s is SortingHelper {
+  return s != null && !Array.isArray(s) && 'sorts' in s && 'toggle' in s;
+}

package/src/react/derived.test.tsx

@@ -0,0 +1,261 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, screen, act } from '@testing-library/react';
+import { ViewModel } from '../ViewModel';
+import { Collection } from '../Collection';
+import { useLocal } from './use-local';
+import { teardownAll } from '../singleton';
+
+interface Item {
+  id: string;
+  name: string;
+  status?: string;
+}
+
+class TestCollection extends Collection<Item> {}
+
+interface TestState {
+  search: string;
+  loading: boolean;
+  error: string | null;
+}
+
+class ItemsViewModel extends ViewModel<TestState> {
+  collection = new TestCollection();
+  computeCount = 0;
+
+  get filtered(): Item[] {
+    this.computeCount++;
+    const { search } = this.state;
+    let items = [...this.collection.items];
+    if (search) {
+      const q = search.toLowerCase();
+      items = items.filter((i) => i.name.toLowerCase().includes(q));
+    }
+    return items;
+  }
+
+  get total(): number {
+    return this.collection.length;
+  }
+
+  get hasResults(): boolean {
+    return this.filtered.length > 0;
+  }
+
+  setSearch(search: string) {
+    this.set({ search });
+  }
+
+  setLoading(loading: boolean) {
+    this.set({ loading });
+  }
+}
+
+const testData: Item[] = [
+  { id: '1', name: 'Alice' },
+  { id: '2', name: 'Bob' },
+  { id: '3', name: 'Charlie' },
+];
+
+describe('derived state - React integration', () => {
+  afterEach(() => {
+    teardownAll();
+  });
+
+  it('useLocal renders with initial state and getter values', () => {
+    function TestComponent() {
+      const [state, vm] = useLocal(ItemsViewModel, {
+        search: '',
+        loading: false,
+        error: null,
+      });
+
+      // Populate collection on first render
+      React.useEffect(() => {
+        vm.collection.reset(testData);
+      }, [vm]);
+
+      return (
+        <div>
+          <span data-testid="search">{state.search}</span>
+          <span data-testid="filtered-count">{vm.filtered.length}</span>
+          <span data-testid="total">{vm.total}</span>
+        </div>
+      );
+    }
+
+    render(<TestComponent />);
+
+    expect(screen.getByTestId('search').textContent).toBe('');
+    expect(screen.getByTestId('filtered-count').textContent).toBe('3');
+    expect(screen.getByTestId('total').textContent).toBe('3');
+  });
+
+  it('state change triggers single re-render with consistent values', () => {
+    let renderCount = 0;
+
+    function TestComponent() {
+      const [state, vm] = useLocal(ItemsViewModel, {
+        search: '',
+        loading: false,
+        error: null,
+      });
+
+      renderCount++;
+
+      React.useEffect(() => {
+        vm.collection.reset(testData);
+      }, [vm]);
+
+      return (
+        <div>
+          <span data-testid="search">{state.search}</span>
+          <span data-testid="filtered-count">{vm.filtered.length}</span>
+          <span data-testid="total">{vm.total}</span>
+          <button data-testid="search-btn" onClick={() => vm.setSearch('alice')}>
+            Search
+          </button>
+        </div>
+      );
+    }
+
+    render(<TestComponent />);
+    const initialRenderCount = renderCount;
+
+    act(() => {
+      screen.getByTestId('search-btn').click();
+    });
+
+    // Should have triggered exactly one additional render
+    expect(renderCount).toBe(initialRenderCount + 1);
+    expect(screen.getByTestId('search').textContent).toBe('alice');
+    expect(screen.getByTestId('filtered-count').textContent).toBe('1');
+    expect(screen.getByTestId('total').textContent).toBe('3');
+  });
+
+  it('collection change triggers re-render with updated getters', () => {
+    function TestComponent() {
+      const [_, vm] = useLocal(ItemsViewModel, {
+        search: '',
+        loading: false,
+        error: null,
+      });
+
+      return (
+        <div>
+          <span data-testid="filtered-count">{vm.filtered.length}</span>
+          <span data-testid="total">{vm.total}</span>
+          <button
+            data-testid="populate-btn"
+            onClick={() => vm.collection.reset(testData)}
+          >
+            Populate
+          </button>
+        </div>
+      );
+    }
+
+    render(<TestComponent />);
+
+    expect(screen.getByTestId('filtered-count').textContent).toBe('0');
+    expect(screen.getByTestId('total').textContent).toBe('0');
+
+    act(() => {
+      screen.getByTestId('populate-btn').click();
+    });
+
+    expect(screen.getByTestId('filtered-count').textContent).toBe('3');
+    expect(screen.getByTestId('total').textContent).toBe('3');
+  });
+
+  it('unrelated state change does not recompute getters', () => {
+    function TestComponent() {
+      const [state, vm] = useLocal(ItemsViewModel, {
+        search: '',
+        loading: false,
+        error: null,
+      });
+
+      React.useEffect(() => {
+        vm.collection.reset(testData);
+      }, [vm]);
+
+      return (
+        <div>
+          <span data-testid="loading">{String(state.loading)}</span>
+          <span data-testid="filtered-count">{vm.filtered.length}</span>
+          <span data-testid="compute-count">{vm.computeCount}</span>
+          <button data-testid="loading-btn" onClick={() => vm.setLoading(true)}>
+            Load
+          </button>
+        </div>
+      );
+    }
+
+    render(<TestComponent />);
+
+    // Initial render computes the getter
+    const initialComputeCount = parseInt(
+      screen.getByTestId('compute-count').textContent || '0'
+    );
+    expect(initialComputeCount).toBeGreaterThan(0);
+
+    act(() => {
+      screen.getByTestId('loading-btn').click();
+    });
+
+    // Component re-renders (loading state changed), but getter returns cached value
+    expect(screen.getByTestId('loading').textContent).toBe('true');
+    expect(screen.getByTestId('filtered-count').textContent).toBe('3');
+    expect(screen.getByTestId('compute-count').textContent).toBe(
+      String(initialComputeCount)
+    );
+  });
+
+  it('React StrictMode double-mount works correctly', () => {
+    function TestComponent() {
+      const [_, vm] = useLocal(ItemsViewModel, {
+        search: '',
+        loading: false,
+        error: null,
+      });
+
+      React.useEffect(() => {
+        vm.collection.reset(testData);
+      }, [vm]);
+
+      return (
+        <div>
+          <span data-testid="filtered-count">{vm.filtered.length}</span>
+          <span data-testid="total">{vm.total}</span>
+          <span data-testid="has-results">{String(vm.hasResults)}</span>
+          <button data-testid="search-btn" onClick={() => vm.setSearch('alice')}>
+            Search
+          </button>
+        </div>
+      );
+    }
+
+    // StrictMode will mount, unmount, and remount the component in dev mode
+    render(
+      <React.StrictMode>
+        <TestComponent />
+      </React.StrictMode>
+    );
+
+    // Should work without errors
+    expect(screen.getByTestId('filtered-count').textContent).toBe('3');
+    expect(screen.getByTestId('total').textContent).toBe('3');
+    expect(screen.getByTestId('has-results').textContent).toBe('true');
+
+    // Interactions should still work correctly
+    act(() => {
+      screen.getByTestId('search-btn').click();
+    });
+
+    expect(screen.getByTestId('filtered-count').textContent).toBe('1');
+    expect(screen.getByTestId('has-results').textContent).toBe('true');
+  });
+});

package/src/react/guards.ts

@@ -0,0 +1,24 @@
+import type { Subscribable } from '../types';
+
+/** @internal Type guard for Subscribable */
+export const isSubscribable = (obj: unknown): obj is Subscribable<unknown> =>
+  obj !== null &&
+  typeof obj === 'object' &&
+  'state' in obj &&
+  'subscribe' in obj &&
+  typeof (obj as Subscribable<unknown>).subscribe === 'function';
+
+/** @internal Type guard for Initializable */
+export const isInitializable = (obj: unknown): obj is { init(): void | Promise<void> } =>
+  obj !== null &&
+  typeof obj === 'object' &&
+  'init' in obj &&
+  typeof (obj as any).init === 'function';
+
+/** @internal Type guard for subscribe-only objects (has subscribe but no state). */
+export const isSubscribeOnly = (obj: unknown): obj is { subscribe(cb: () => void): () => void } =>
+  obj !== null &&
+  typeof obj === 'object' &&
+  !('state' in obj) &&
+  'subscribe' in obj &&
+  typeof (obj as any).subscribe === 'function';

package/src/react/index.ts

@@ -0,0 +1,40 @@
+// Types
+export type { StateOf, ItemOf, SingletonClass, ProviderRegistry } from './types';
+
+// Generic reactive state bindings
+export { useInstance } from './use-instance';
+export { useLocal } from './use-local';
+export { useSingleton } from './use-singleton';
+
+// Model (specialized - returns rich ModelHandle with validation)
+export { useModel, useModelRef, useField } from './use-model';
+export type { ModelHandle, FieldHandle } from './use-model';
+
+// EventBus (specialized)
+export { useEvent, useEmit } from './use-event-bus';
+
+// Utilities
+export { useTeardown } from './use-teardown';
+export { Provider, useResolve } from './provider';
+export type { ProviderProps } from './provider';
+
+// Headless components
+export { DataTable } from './components/DataTable';
+export type { DataTableProps } from './components/DataTable';
+export { CardList } from './components/CardList';
+export type { CardListProps } from './components/CardList';
+export { InfiniteScroll } from './components/InfiniteScroll';
+export type { InfiniteScrollProps } from './components/InfiniteScroll';
+
+// Component types
+export type {
+  Column,
+  SortHeaderProps,
+  SelectionState,
+  SelectionHelper,
+  PaginationState,
+  PaginationHelper,
+  PaginationInfo,
+  SortingHelper,
+  AsyncStateProps,
+} from './components/types';

package/src/react/provider.test.tsx

@@ -0,0 +1,143 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { render, screen, act } from '@testing-library/react';
+import { useState } from 'react';
+import { Service } from '../Service';
+import { ViewModel } from '../ViewModel';
+import { teardownAll } from '../singleton';
+import { Provider, useResolve } from './provider';
+
+class ApiService extends Service {
+  fetchData(): string {
+    return 'real-data';
+  }
+}
+
+class MockApiService extends Service {
+  fetchData(): string {
+    return 'mock-data';
+  }
+}
+
+interface CountState {
+  count: number;
+}
+
+class CounterVM extends ViewModel<CountState> {
+  constructor() {
+    super({ count: 0 });
+  }
+
+  increment() {
+    this.set((prev) => ({ count: prev.count + 1 }));
+  }
+}
+
+function ApiConsumer() {
+  const api = useResolve(ApiService);
+  const [data, setData] = useState('');
+
+  return (
+    <div>
+      <div data-testid="data">{data}</div>
+      <button onClick={() => setData(api.fetchData())}>Fetch</button>
+    </div>
+  );
+}
+
+function CounterConsumer() {
+  const vm = useResolve(CounterVM);
+  return <div data-testid="count">{vm.state.count}</div>;
+}
+
+describe('Provider and useResolve', () => {
+  afterEach(() => {
+    teardownAll();
+  });
+
+  it('should resolve from provider when provided', () => {
+    const mockApi = new MockApiService();
+
+    render(
+      <Provider provide={[[ApiService, mockApi]]}>
+        <ApiConsumer />
+      </Provider>
+    );
+
+    act(() => {
+      screen.getByRole('button').click();
+    });
+
+    expect(screen.getByTestId('data').textContent).toBe('mock-data');
+  });
+
+  it('should fallback to singleton when not provided', () => {
+    render(<ApiConsumer />);
+
+    act(() => {
+      screen.getByRole('button').click();
+    });
+
+    expect(screen.getByTestId('data').textContent).toBe('real-data');
+  });
+
+  it('should work with ViewModels', () => {
+    const mockVm = new CounterVM();
+    mockVm.increment();
+    mockVm.increment();
+
+    render(
+      <Provider provide={[[CounterVM, mockVm]]}>
+        <CounterConsumer />
+      </Provider>
+    );
+
+    expect(screen.getByTestId('count').textContent).toBe('2');
+  });
+
+  it('should provide multiple dependencies', () => {
+    const mockApi = new MockApiService();
+    const mockVm = new CounterVM();
+    mockVm.increment();
+
+    render(
+      <Provider
+        provide={[
+          [ApiService, mockApi],
+          [CounterVM, mockVm],
+        ]}
+      >
+        <ApiConsumer />
+        <CounterConsumer />
+      </Provider>
+    );
+
+    act(() => {
+      screen.getByRole('button').click();
+    });
+
+    expect(screen.getByTestId('data').textContent).toBe('mock-data');
+    expect(screen.getByTestId('count').textContent).toBe('1');
+  });
+
+  it('should allow nested providers', () => {
+    const outerMock = new MockApiService();
+    const innerVm = new CounterVM();
+    innerVm.increment();
+
+    render(
+      <Provider provide={[[ApiService, outerMock]]}>
+        <Provider provide={[[CounterVM, innerVm]]}>
+          <ApiConsumer />
+          <CounterConsumer />
+        </Provider>
+      </Provider>
+    );
+
+    // Note: Inner provider only has CounterVM, so ApiService
+    // will fallback to singleton (not outer mock) due to context replacement
+    // This is expected React context behavior
+    expect(screen.getByTestId('count').textContent).toBe('1');
+  });
+});

package/src/react/provider.tsx

@@ -0,0 +1,55 @@
+import { createContext, useContext, useMemo, type ReactNode } from 'react';
+import { singleton } from '../singleton';
+import type { Disposable } from '../types';
+import type { ProviderRegistry } from './types';
+
+const ProviderContext = createContext<ProviderRegistry | null>(null);
+
+/** Props for the `Provider` component used to inject test/Storybook dependencies. */
+export interface ProviderProps {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  provide: Array<[new (...args: any[]) => any, any]>;
+  children: ReactNode;
+}
+
+/**
+ * DI container for testing and Storybook.
+ */
+export function Provider({ provide, children }: ProviderProps): ReactNode {
+  const registry = useMemo(() => {
+    const map: ProviderRegistry = new Map();
+    for (const [Class, instance] of provide) {
+      map.set(Class, instance);
+    }
+    return map;
+  }, [provide]);
+
+  return (
+    <ProviderContext.Provider value={registry}>
+      {children}
+    </ProviderContext.Provider>
+  );
+}
+
+/**
+ * Resolve from Provider context or fallback to singleton().
+ * If the class defines `static DEFAULT_STATE`, no constructor args are needed.
+ */
+export function useResolve<T>(
+  Class: (new (...args: any[]) => T) & { DEFAULT_STATE: unknown },
+): T;
+export function useResolve<T, Args extends unknown[] = unknown[]>(
+  Class: new (...args: Args) => T,
+  ...args: Args
+): T;
+export function useResolve<T, Args extends unknown[] = unknown[]>(
+  Class: (new (...args: Args) => T) & { DEFAULT_STATE?: unknown },
+  ...args: Args
+): T {
+  const registry = useContext(ProviderContext);
+
+  if (registry?.has(Class)) {
+    return registry.get(Class) as T;
+  }
+  return singleton(Class as new (...args: Args) => T & Disposable, ...args);
+}