mvc-kit 2.0.0 → 2.1.0

package/agent-config/claude-code/skills/scaffold/templates/controller.md

@@ -0,0 +1,56 @@
+# Controller Template: {{Name}}
+
+## {{Name}}Controller.ts
+
+```typescript
+import { Controller } from 'mvc-kit';
+
+export class {{Name}}Controller extends Controller {
+  constructor(
+    // TODO: Inject dependencies
+    // private viewModelA: SomeViewModel,
+    // private viewModelB: AnotherViewModel,
+  ) {
+    super();
+  }
+
+  protected onInit() {
+    // Wire up cross-ViewModel subscriptions
+    // this.subscribeTo(this.viewModelA, () => this.onViewModelAChanged());
+  }
+
+  // TODO: Add orchestration methods
+  // async submit() {
+  //   const items = this.viewModelA.state.items;
+  //   await this.viewModelB.process(items);
+  // }
+
+  // private onViewModelAChanged() {
+  //   // React to changes in viewModelA
+  // }
+}
+```
+
+## Usage
+
+```tsx
+import { useLocal } from 'mvc-kit/react';
+import { {{Name}}Controller } from '../controllers/{{Name}}Controller';
+
+function {{Name}}Page() {
+  const controller = useLocal(() => new {{Name}}Controller(/* deps */));
+
+  return (
+    <div>
+      <button onClick={() => controller.submit()}>Submit</button>
+    </div>
+  );
+}
+```
+
+## Notes
+
+- **Rare** — most orchestration fits in a single ViewModel
+- Use only when coordinating **multiple ViewModels** in a single workflow
+- Has `disposeSignal`, `subscribeTo`, `addCleanup` — but no state, no getters, no async tracking
+- Component-scoped via `useLocal` with factory function

package/agent-config/claude-code/skills/scaffold/templates/eventbus.md

@@ -0,0 +1,54 @@
+# EventBus Template: {{Name}}
+
+## {{Name}}EventBus.ts
+
+```typescript
+import { EventBus } from 'mvc-kit';
+
+export interface {{Name}}Events {
+  // TODO: Define your event map
+  // 'item:created': { id: string };
+  // 'item:deleted': { id: string };
+  // 'notification': { message: string; severity: 'success' | 'error' | 'info' };
+}
+
+export class {{Name}}EventBus extends EventBus<{{Name}}Events> {}
+```
+
+## Usage
+
+```typescript
+import { singleton } from 'mvc-kit';
+import { {{Name}}EventBus } from '../events/{{Name}}EventBus';
+
+// In a ViewModel:
+private bus = singleton({{Name}}EventBus);
+
+// Emit
+this.bus.emit('item:created', { id: '123' });
+
+// Subscribe (with auto-cleanup)
+this.addCleanup(
+  this.bus.on('item:deleted', ({ id }) => {
+    this.set({ items: this.state.items.filter(i => i.id !== id) });
+  }),
+);
+```
+
+```tsx
+// In a React component:
+import { useEvent } from 'mvc-kit/react';
+import { singleton } from 'mvc-kit';
+import { {{Name}}EventBus } from '../events/{{Name}}EventBus';
+
+const bus = singleton({{Name}}EventBus);
+useEvent(bus, 'notification', ({ message }) => {
+  toast.show(message);
+});
+```
+
+## Notes
+
+- Use EventBus for **cross-cutting** events between unrelated parts of the app
+- For ViewModel-to-component events (toasts, navigation), prefer the **second generic parameter** on ViewModel instead
+- Keep the event map small — past 10-15 events, concerns may be entangled

package/agent-config/claude-code/skills/scaffold/templates/model.md

@@ -0,0 +1,102 @@
+# Model Template: {{Name}}
+
+## {{Name}}Model.ts
+
+```typescript
+import { Model } from 'mvc-kit';
+import type { ValidationErrors } from 'mvc-kit';
+
+export interface {{Name}}FormState {
+  name: string;
+  // TODO: Add your fields
+}
+
+export class {{Name}}Model extends Model<{{Name}}FormState> {
+  setName(name: string) { this.set({ name }); }
+  // TODO: Add setters for each field
+
+  protected validate(state: {{Name}}FormState): ValidationErrors<{{Name}}FormState> {
+    const errors: Partial<Record<keyof {{Name}}FormState, string>> = {};
+    if (!state.name.trim()) errors.name = 'Name is required';
+    // TODO: Add validation rules
+    return errors;
+  }
+}
+```
+
+## {{Name}}Model.test.ts
+
+```typescript
+import { describe, test, expect } from 'vitest';
+import { {{Name}}Model } from './{{Name}}Model';
+
+describe('{{Name}}Model', () => {
+  function create(overrides: Partial<{ name: string }> = {}) {
+    return new {{Name}}Model({
+      name: '',
+      ...overrides,
+    });
+  }
+
+  test('validates required name', () => {
+    const model = create();
+    expect(model.valid).toBe(false);
+    expect(model.errors.name).toBe('Name is required');
+    model.dispose();
+  });
+
+  test('valid when all fields filled', () => {
+    const model = create({ name: 'Test' });
+    expect(model.valid).toBe(true);
+    expect(model.errors.name).toBeUndefined();
+    model.dispose();
+  });
+
+  test('tracks dirty state', () => {
+    const model = create({ name: 'Original' });
+    expect(model.dirty).toBe(false);
+
+    model.setName('Changed');
+    expect(model.dirty).toBe(true);
+
+    model.rollback();
+    expect(model.state.name).toBe('Original');
+    expect(model.dirty).toBe(false);
+    model.dispose();
+  });
+
+  test('commit resets dirty baseline', () => {
+    const model = create({ name: 'Original' });
+    model.setName('Updated');
+    expect(model.dirty).toBe(true);
+
+    model.commit();
+    expect(model.dirty).toBe(false);
+    model.dispose();
+  });
+});
+```
+
+## React Usage
+
+```tsx
+import { useModel, useField } from 'mvc-kit/react';
+import { {{Name}}Model } from '../models/{{Name}}Model';
+
+function {{Name}}Form() {
+  const { state, errors, valid, dirty, model } = useModel(
+    () => new {{Name}}Model({ name: '' }),
+  );
+
+  return (
+    <form onSubmit={e => { e.preventDefault(); /* handle submit */ }}>
+      <input
+        value={state.name}
+        onChange={e => model.setName(e.target.value)}
+      />
+      {errors.name && <span className="error">{errors.name}</span>}
+      <button disabled={!valid || !dirty}>Save</button>
+    </form>
+  );
+}
+```

package/agent-config/claude-code/skills/scaffold/templates/page-component.md

@@ -0,0 +1,58 @@
+# Page Component Template: {{Name}}
+
+## {{Name}}Page.tsx
+
+```tsx
+import { useLocal } from 'mvc-kit/react';
+import { {{Name}}ViewModel } from '../viewmodels/{{Name}}ViewModel';
+
+export function {{Name}}Page() {
+  const [state, vm] = useLocal({{Name}}ViewModel, {
+    items: [],
+    search: '',
+    // TODO: Add initial state matching {{Name}}ViewModel's State interface
+  });
+  const { loading, error } = vm.async.load;
+
+  // Optional: subscribe to ViewModel events
+  // useEvent(vm, 'saved', ({ id }) => toast.success(`Saved ${id}`));
+
+  return (
+    <div>
+      <h1>{{Name}}</h1>
+
+      {/* Filters */}
+      <input
+        placeholder="Search..."
+        value={state.search}
+        onChange={e => vm.setSearch(e.target.value)}
+      />
+
+      {/* Loading/Error states from async tracking */}
+      {loading && <p>Loading...</p>}
+      {error && <p className="error">{error}</p>}
+
+      {/* Data — use vm.x for computed values */}
+      {!loading && (
+        <div>
+          {/* TODO: Replace with your data display */}
+          <p>Showing {vm.filtered.length} of {vm.total}</p>
+          <ul>
+            {vm.filtered.map((item: any) => (
+              <li key={item.id}>{JSON.stringify(item)}</li>
+            ))}
+          </ul>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+## Rules
+
+- **One ViewModel per component** via `useLocal`
+- **No `useEffect`** for data loading — `onInit()` handles it
+- **No `useState`/`useMemo`/`useCallback`** — the ViewModel is the hook
+- Read `state.x` for raw values, `vm.x` for computed, `vm.async.x` for loading/error
+- Connected components own a ViewModel; extract presentational children that receive props

package/agent-config/claude-code/skills/scaffold/templates/service.md

@@ -0,0 +1,101 @@
+# Service Template: {{Name}}
+
+## {{Name}}Service.ts
+
+```typescript
+import { Service, HttpError } from 'mvc-kit';
+
+// TODO: Import or define your data types
+// import type { {{Name}}Item } from '../types/{{name}}';
+
+export class {{Name}}Service extends Service {
+  private baseUrl = '/api/{{name}}s'; // TODO: Set your API path
+
+  async getAll(signal?: AbortSignal): Promise<any[]> {
+    const res = await fetch(this.baseUrl, { signal });
+    if (!res.ok) throw new HttpError(res.status, res.statusText);
+    return res.json();
+  }
+
+  async getById(id: string, signal?: AbortSignal): Promise<any> {
+    const res = await fetch(`${this.baseUrl}/${id}`, { signal });
+    if (!res.ok) throw new HttpError(res.status, res.statusText);
+    return res.json();
+  }
+
+  async create(data: any, signal?: AbortSignal): Promise<any> {
+    const res = await fetch(this.baseUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+      signal,
+    });
+    if (!res.ok) throw new HttpError(res.status, res.statusText);
+    return res.json();
+  }
+
+  async update(id: string, data: any, signal?: AbortSignal): Promise<any> {
+    const res = await fetch(`${this.baseUrl}/${id}`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+      signal,
+    });
+    if (!res.ok) throw new HttpError(res.status, res.statusText);
+    return res.json();
+  }
+
+  async delete(id: string, signal?: AbortSignal): Promise<void> {
+    const res = await fetch(`${this.baseUrl}/${id}`, {
+      method: 'DELETE',
+      signal,
+    });
+    if (!res.ok) throw new HttpError(res.status, res.statusText);
+  }
+}
+```
+
+## {{Name}}Service.test.ts
+
+```typescript
+import { describe, test, expect, beforeEach, vi } from 'vitest';
+import { teardownAll } from 'mvc-kit';
+import { {{Name}}Service } from './{{Name}}Service';
+
+beforeEach(() => teardownAll());
+
+describe('{{Name}}Service', () => {
+  test('getAll fetches items', async () => {
+    const mockData = [{ id: '1' }];
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      new Response(JSON.stringify(mockData), { status: 200 }),
+    );
+
+    const service = new {{Name}}Service();
+    const result = await service.getAll();
+    expect(result).toEqual(mockData);
+
+    vi.restoreAllMocks();
+    service.dispose();
+  });
+
+  test('getAll throws HttpError on failure', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      new Response(null, { status: 500, statusText: 'Internal Server Error' }),
+    );
+
+    const service = new {{Name}}Service();
+    await expect(service.getAll()).rejects.toThrow('Internal Server Error');
+
+    vi.restoreAllMocks();
+    service.dispose();
+  });
+});
+```
+
+## Rules
+
+- **Stateless** — no caching (that's a Collection's job)
+- **Accept `AbortSignal`** — lets ViewModels cancel via `disposeSignal`
+- **Throw `HttpError`** — carries HTTP status for `classifyError()` to produce canonical codes
+- **No knowledge of ViewModels or Collections** — Services are at the bottom of the dependency graph

package/agent-config/claude-code/skills/scaffold/templates/viewmodel.md

@@ -0,0 +1,128 @@
+# ViewModel Template: {{Name}}
+
+## {{Name}}ViewModel.ts
+
+```typescript
+import { ViewModel, singleton } from 'mvc-kit';
+// import { {{Name}}Service } from '../services/{{Name}}Service';
+// import { {{Name}}Collection } from '../collections/{{Name}}Collection';
+
+interface {{Name}}State {
+  items: any[]; // TODO: Replace with your item type
+  search: string;
+}
+
+// Optional: define events for toasts, navigation, etc.
+// interface {{Name}}Events {
+//   saved: { id: string };
+// }
+
+export class {{Name}}ViewModel extends ViewModel<{{Name}}State> {
+  // --- Private fields ---
+  // private service = singleton({{Name}}Service);
+  // private collection = singleton({{Name}}Collection);
+
+  // --- Computed getters ---
+  get filtered(): any[] {
+    const { items, search } = this.state;
+    if (!search) return items;
+    const q = search.toLowerCase();
+    return items.filter(item =>
+      JSON.stringify(item).toLowerCase().includes(q),
+    );
+  }
+
+  get total(): number {
+    return this.state.items.length;
+  }
+
+  get hasResults(): boolean {
+    return this.filtered.length > 0;
+  }
+
+  // --- Lifecycle ---
+  protected onInit() {
+    // Subscribe to collection and mirror data into state
+    // this.subscribeTo(this.collection, () => {
+    //   this.set({ items: this.collection.items });
+    // });
+
+    // Smart init: use cached data or fetch fresh
+    // if (this.collection.length > 0) {
+    //   this.set({ items: this.collection.items });
+    // } else {
+    //   this.load();
+    // }
+
+    this.load();
+  }
+
+  // --- Actions ---
+  async load() {
+    // const data = await this.service.getAll(this.disposeSignal);
+    // this.collection.reset(data);
+    // TODO: implement data loading
+  }
+
+  // --- Setters ---
+  setSearch(search: string) { this.set({ search }); }
+}
+```
+
+## {{Name}}ViewModel.test.ts
+
+```typescript
+import { describe, test, expect, beforeEach } from 'vitest';
+import { teardownAll } from 'mvc-kit';
+import { {{Name}}ViewModel } from './{{Name}}ViewModel';
+
+beforeEach(() => teardownAll());
+
+describe('{{Name}}ViewModel', () => {
+  function create(overrides: Partial<{ items: any[]; search: string }> = {}) {
+    return new {{Name}}ViewModel({
+      items: [],
+      search: '',
+      ...overrides,
+    });
+  }
+
+  test('initializes with default state', () => {
+    const vm = create();
+    expect(vm.state.items).toEqual([]);
+    expect(vm.state.search).toBe('');
+    vm.dispose();
+  });
+
+  test('setSearch updates search state', () => {
+    const vm = create();
+    vm.setSearch('test');
+    expect(vm.state.search).toBe('test');
+    vm.dispose();
+  });
+
+  test('filtered getter applies search', () => {
+    const vm = create({
+      items: [
+        { id: '1', name: 'Alpha' },
+        { id: '2', name: 'Beta' },
+      ],
+    });
+
+    expect(vm.filtered).toHaveLength(2);
+
+    vm.setSearch('alpha');
+    expect(vm.filtered).toHaveLength(1);
+
+    vm.dispose();
+  });
+
+  test('total returns item count', () => {
+    const vm = create({
+      items: [{ id: '1' }, { id: '2' }, { id: '3' }],
+    });
+    expect(vm.total).toBe(3);
+    vm.dispose();
+  });
+});
+```