mvc-kit 2.12.5 → 2.13.1

package/examples/react/WorkerApp/src/types/conversation.ts

@@ -0,0 +1,7 @@
+export interface ConversationState {
+  id: string;
+  participantIds: string[];
+  lastMessage: string;
+  unreadCount: number;
+  updatedAt: number;
+}

package/examples/react/WorkerApp/src/types/message.ts

@@ -0,0 +1,7 @@
+export interface MessageState {
+  id: string;
+  conversationId: string;
+  senderId: string;
+  text: string;
+  sentAt: number;
+}

package/examples/react/WorkerApp/src/types/shift.ts

@@ -0,0 +1,13 @@
+export interface BreakEntry {
+  start: number;
+  end: number | null;
+}
+
+export interface ShiftState {
+  id: string;
+  workerId: string;
+  siteId: string;
+  clockIn: number;
+  clockOut: number | null;
+  breaks: BreakEntry[];
+}

package/examples/react/WorkerApp/src/types/site.ts

@@ -0,0 +1,8 @@
+export interface SiteState {
+  id: string;
+  name: string;
+  type: 'residential' | 'commercial' | 'industrial' | 'infrastructure';
+  status: 'active' | 'paused' | 'completed';
+  address: string;
+  workerCount: number;
+}

package/examples/react/WorkerApp/src/types/worker.ts

@@ -0,0 +1,8 @@
+export interface WorkerState {
+  id: string;
+  name: string;
+  email: string;
+  role: 'foreman' | 'electrician' | 'plumber' | 'carpenter' | 'laborer';
+  status: 'available' | 'on-shift' | 'on-break' | 'offline';
+  avatar: string;
+}

package/examples/react/WorkerApp/src/viewmodels/AuthViewModel.ts

@@ -0,0 +1,41 @@
+import { ViewModel, singleton } from 'mvc-kit';
+import type { WorkerState } from '../types/worker';
+import { MOCK_WORKERS } from '../mock/workers';
+import { mockFetch } from '../mock/delay';
+import { AppEventBus } from '../events/AppEventBus';
+
+interface AuthState {
+  worker: WorkerState | null;
+  isAuthenticated: boolean;
+}
+
+export class AuthViewModel extends ViewModel<AuthState> {
+  static DEFAULT_STATE: AuthState = { worker: null, isAuthenticated: false };
+
+  // --- Private fields ---
+  private bus = singleton(AppEventBus);
+
+  // --- Computed getters ---
+  get displayName(): string {
+    const { worker } = this.state;
+    return worker ? worker.name : '';
+  }
+
+  get initials(): string {
+    const { worker } = this.state;
+    return worker ? worker.avatar : '';
+  }
+
+  // --- Actions ---
+  async login(email: string) {
+    const worker = MOCK_WORKERS.find(w => w.email === email) ?? MOCK_WORKERS[0]!;
+    await mockFetch(null, 300);
+    this.set({ worker, isAuthenticated: true });
+    this.bus.emit('toast:show', { message: `Welcome, ${worker.name}!`, severity: 'success' });
+  }
+
+  logout() {
+    this.set({ worker: null, isAuthenticated: false });
+    this.bus.emit('toast:show', { message: 'Logged out', severity: 'info' });
+  }
+}

package/examples/react/WorkerApp/src/viewmodels/ConversationsViewModel.ts

@@ -0,0 +1,83 @@
+import { ViewModel, singleton } from 'mvc-kit';
+import type { ConversationState } from '../types/conversation';
+import { ConversationsResource } from '../resources/ConversationsResource';
+import { WorkersResource } from '../resources/WorkersResource';
+import { AuthViewModel } from './AuthViewModel';
+
+export interface ConversationDisplay extends ConversationState {
+  displayName: string;
+}
+
+interface ConversationsViewState {
+  search: string;
+  selectedId: string | null;
+  currentWorkerId: string;
+}
+
+export class ConversationsViewModel extends ViewModel<ConversationsViewState> {
+  // --- Private fields ---
+  private resource = singleton(ConversationsResource);
+  private workers = singleton(WorkersResource);
+
+  // --- Computed getters ---
+  get items(): ConversationState[] {
+    return this.resource.items as ConversationState[];
+  }
+
+  get filtered(): ConversationDisplay[] {
+    const { search, currentWorkerId } = this.state;
+    let result = this.items;
+
+    if (search) {
+      const q = search.toLowerCase();
+      result = result.filter(conv =>
+        conv.participantIds.some(id => {
+          const worker = this.workers.get(id);
+          return worker ? worker.name.toLowerCase().includes(q) : false;
+        }),
+      );
+    }
+
+    return result.map(conv => ({
+      ...conv,
+      displayName: conv.participantIds
+        .filter(id => id !== currentWorkerId)
+        .map(id => {
+          const worker = this.workers.get(id);
+          return worker ? worker.name : 'Unknown';
+        })
+        .join(', '),
+    }));
+  }
+
+  get selected(): ConversationDisplay | undefined {
+    return this.filtered.find(c => c.id === this.state.selectedId);
+  }
+
+  get totalUnread(): number {
+    return this.items.reduce((sum, c) => sum + c.unreadCount, 0);
+  }
+
+  // --- Lifecycle ---
+  protected onInit() {
+    const auth = singleton(AuthViewModel);
+    const currentWorkerId = auth.state.worker?.id ?? '';
+    this.set({ currentWorkerId });
+
+    if (this.workers.length === 0) this.workers.loadAll();
+    if (this.resource.length === 0) this.load();
+  }
+
+  // --- Actions ---
+  async load() {
+    const { currentWorkerId } = this.state;
+    await this.resource.loadAll(currentWorkerId);
+  }
+
+  selectConversation(id: string) {
+    this.set({ selectedId: id });
+  }
+
+  // --- Setters ---
+  setSearch(search: string) { this.set({ search }); }
+}

package/examples/react/WorkerApp/src/viewmodels/MessageThreadViewModel.ts

@@ -0,0 +1,113 @@
+import { ViewModel, singleton, Feed } from 'mvc-kit';
+import type { MessageState } from '../types/message';
+import { MessagesResource } from '../resources/MessagesResource';
+import { MessagingChannel } from '../channels/MessagingChannel';
+import { WorkersResource } from '../resources/WorkersResource';
+import { AuthViewModel } from './AuthViewModel';
+
+interface ThreadState {}
+
+interface ThreadEvents {
+  messageSent: { conversationId: string };
+}
+
+export class MessageThreadViewModel extends ViewModel<ThreadState, ThreadEvents> {
+  // --- Private fields ---
+  private resource = singleton(MessagesResource);
+  private channel = singleton(MessagingChannel);
+  private workers = singleton(WorkersResource);
+  private _loadController: AbortController | null = null;
+  private _conversationId: string = '';
+
+  readonly feed = new Feed<MessageState>();
+
+  // --- Computed getters ---
+  get sortedMessages(): MessageState[] {
+    return [...this.feed.items].sort((a, b) => a.sentAt - b.sentAt);
+  }
+
+  get pending() {
+    return this.resource.pending;
+  }
+
+  get hasPendingMessages(): boolean {
+    return this.resource.pending.hasPending;
+  }
+
+  get hasFailedMessages(): boolean {
+    return this.resource.pending.hasFailed;
+  }
+
+  // --- Lifecycle ---
+  protected onInit() {
+    this.listenTo(this.channel, 'newMessage', (msg) => {
+      if (msg.conversationId === this._conversationId) {
+        this.feed.push(msg);
+      }
+    });
+    this.channel.connect();
+  }
+
+  // --- Actions ---
+  async loadConversation(conversationId: string) {
+    this._loadController?.abort();
+    this._loadController = new AbortController();
+    this._conversationId = conversationId;
+
+    this.feed.reset();
+
+    const page = await this.resource.loadMessages(
+      conversationId,
+      AbortSignal.any([this.disposeSignal, this._loadController.signal]),
+    );
+    this.feed.appendPage(page);
+  }
+
+  async loadOlderMessages() {
+    if (!this.feed.hasMore || !this._conversationId) return;
+
+    const page = await this.resource.loadMessages(
+      this._conversationId,
+      this.disposeSignal,
+      { cursor: this.feed.cursor },
+    );
+    this.feed.appendPage(page);
+  }
+
+  sendMessage(conversationId: string, text: string, recipientName: string) {
+    const trimmed = text.trim();
+    if (!trimmed) return;
+
+    const auth = singleton(AuthViewModel);
+    const senderId = auth.state.worker?.id ?? '';
+    const tempId = `temp-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+
+    // Optimistic: add to feed immediately
+    const optimisticMsg: MessageState = {
+      id: tempId,
+      conversationId,
+      senderId,
+      text: trimmed,
+      sentAt: Date.now(),
+    };
+    this.feed.push(optimisticMsg);
+
+    // Enqueue via resource Pending for retry — meta provides UI context
+    this.resource.enqueueSend(tempId, conversationId, senderId, trimmed, recipientName);
+
+    this.emit('messageSent', { conversationId });
+  }
+
+  retryMessage(id: string) {
+    this.resource.pending.retry(id);
+  }
+
+  dismissMessage(id: string) {
+    this.resource.pending.dismiss(id);
+  }
+
+  getSenderName(senderId: string): string {
+    const worker = this.workers.get(senderId);
+    return worker ? worker.name : 'Unknown';
+  }
+}

package/examples/react/WorkerApp/src/viewmodels/ShiftViewModel.ts

@@ -0,0 +1,147 @@
+import { ViewModel, singleton } from 'mvc-kit';
+import type { ShiftState } from '../types/shift';
+import type { SiteState } from '../types/site';
+import { ShiftResource } from '../resources/ShiftResource';
+import { SitesResource } from '../resources/SitesResource';
+import { AuthViewModel } from './AuthViewModel';
+
+interface ShiftViewState {
+  selectedSiteId: string | null;
+  now: number;
+}
+
+export class ShiftViewModel extends ViewModel<ShiftViewState> {
+  // --- Private fields ---
+  private shiftResource = singleton(ShiftResource);
+  private sites = singleton(SitesResource);
+  private auth = singleton(AuthViewModel);
+  private _timer: ReturnType<typeof setInterval> | null = null;
+
+  // --- Computed getters ---
+  get currentShift(): ShiftState | null {
+    const items = this.shiftResource.items as ShiftState[];
+    return items.length > 0 ? items[0]! : null;
+  }
+
+  get isOnShift(): boolean {
+    return this.currentShift !== null && this.currentShift.clockOut === null;
+  }
+
+  get isOnBreak(): boolean {
+    const shift = this.currentShift;
+    if (!shift) return false;
+    return shift.breaks.some(b => b.end === null);
+  }
+
+  get shiftDuration(): number {
+    const shift = this.currentShift;
+    if (!shift) return 0;
+    const end = shift.clockOut ?? this.state.now;
+    return end - shift.clockIn;
+  }
+
+  get breakDuration(): number {
+    const shift = this.currentShift;
+    if (!shift) return 0;
+    return shift.breaks.reduce((sum, b) => {
+      const end = b.end ?? this.state.now;
+      return sum + (end - b.start);
+    }, 0);
+  }
+
+  get formattedShiftTime(): string {
+    return formatDuration(this.shiftDuration);
+  }
+
+  get formattedBreakTime(): string {
+    return formatDuration(this.breakDuration);
+  }
+
+  get currentSiteName(): string {
+    const shift = this.currentShift;
+    if (!shift) return '';
+    const site = this.sites.get(shift.siteId) as SiteState | undefined;
+    return site?.name ?? '';
+  }
+
+  get availableSites(): SiteState[] {
+    return (this.sites.items as SiteState[]).filter(s => s.status === 'active');
+  }
+
+  get pending() {
+    return this.shiftResource.pending;
+  }
+
+  get hasPendingOps(): boolean {
+    return this.shiftResource.pending.hasPending;
+  }
+
+  get hasFailedOps(): boolean {
+    return this.shiftResource.pending.hasFailed;
+  }
+
+  // --- Lifecycle ---
+  protected onInit() {
+    const workerId = this.auth.state.worker?.id;
+    if (workerId && this.shiftResource.length === 0) this.load();
+    if (this.sites.length === 0) this.sites.loadAll();
+
+    this._timer = setInterval(() => {
+      this.set({ now: Date.now() });
+    }, 1000);
+    this.addCleanup(() => {
+      if (this._timer) clearInterval(this._timer);
+    });
+  }
+
+  // --- Actions ---
+  async load() {
+    const workerId = this.auth.state.worker?.id;
+    if (!workerId) return;
+    await this.shiftResource.loadCurrent(workerId);
+  }
+
+  clockIn() {
+    const workerId = this.auth.state.worker?.id;
+    const siteId = this.state.selectedSiteId;
+    if (!workerId || !siteId) return;
+    this.shiftResource.clockIn(workerId, siteId, this.currentSiteName || siteId);
+  }
+
+  clockOut() {
+    const shift = this.currentShift;
+    if (!shift) return;
+    this.shiftResource.clockOut(shift.id, this.currentSiteName);
+  }
+
+  startBreak() {
+    const shift = this.currentShift;
+    if (!shift) return;
+    this.shiftResource.startBreak(shift.id, this.currentSiteName);
+  }
+
+  endBreak() {
+    const shift = this.currentShift;
+    if (!shift) return;
+    this.shiftResource.endBreak(shift.id, this.currentSiteName);
+  }
+
+  retryAll() {
+    this.shiftResource.pending.retryAll();
+  }
+
+  dismissAll() {
+    this.shiftResource.pending.dismissAll();
+  }
+
+  // --- Setters ---
+  selectSite(siteId: string) { this.set({ selectedSiteId: siteId }); }
+}
+
+function formatDuration(ms: number): string {
+  const totalSeconds = Math.floor(ms / 1000);
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+  return `${String(hours).padStart(2, '0')}:${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')}`;
+}

package/examples/react/WorkerApp/src/viewmodels/SitesViewModel.ts

@@ -0,0 +1,82 @@
+import { ViewModel, singleton, Sorting, Pagination, Selection } from 'mvc-kit';
+import type { SiteState } from '../types/site';
+import { SitesResource } from '../resources/SitesResource';
+
+interface SitesViewState {
+  search: string;
+  typeFilter: 'all' | SiteState['type'];
+  statusFilter: 'all' | SiteState['status'];
+}
+
+export class SitesViewModel extends ViewModel<SitesViewState> {
+  // --- Private fields ---
+  private resource = singleton(SitesResource);
+
+  readonly sorting = new Sorting<SiteState>({ sorts: [{ key: 'name', direction: 'asc' }] });
+  readonly pagination = new Pagination({ pageSize: 10 });
+  readonly selection = new Selection<string>();
+
+  // --- Computed getters ---
+  get items(): SiteState[] {
+    return this.resource.items as SiteState[];
+  }
+
+  get filtered(): SiteState[] {
+    const { search, typeFilter, statusFilter } = this.state;
+    let result = this.items;
+
+    if (search) {
+      const q = search.toLowerCase();
+      result = result.filter(site =>
+        site.name.toLowerCase().includes(q) ||
+        site.address.toLowerCase().includes(q),
+      );
+    }
+    if (typeFilter !== 'all') {
+      result = result.filter(site => site.type === typeFilter);
+    }
+    if (statusFilter !== 'all') {
+      result = result.filter(site => site.status === statusFilter);
+    }
+    return result;
+  }
+
+  get sorted(): SiteState[] {
+    return this.sorting.apply(this.filtered);
+  }
+
+  get paged(): SiteState[] {
+    return this.pagination.apply(this.sorted);
+  }
+
+  get total(): number {
+    return this.items.length;
+  }
+
+  get filteredCount(): number {
+    return this.filtered.length;
+  }
+
+  get hasResults(): boolean {
+    return this.filtered.length > 0;
+  }
+
+  get selectedItems(): SiteState[] {
+    return this.selection.selectedFrom(this.filtered, site => site.id);
+  }
+
+  // --- Lifecycle ---
+  protected onInit() {
+    if (this.resource.length === 0) this.load();
+  }
+
+  // --- Actions ---
+  async load() {
+    await this.resource.loadAll();
+  }
+
+  // --- Setters ---
+  setSearch(search: string) { this.set({ search }); this.pagination.reset(); }
+  setTypeFilter(typeFilter: SitesViewState['typeFilter']) { this.set({ typeFilter }); this.pagination.reset(); }
+  setStatusFilter(statusFilter: SitesViewState['statusFilter']) { this.set({ statusFilter }); this.pagination.reset(); }
+}

package/examples/react/WorkerApp/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": false,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": [],
+    "baseUrl": ".",
+    "paths": {
+      "mvc-kit": ["../../../src/index.ts"],
+      "mvc-kit/react": ["../../../src/react/index.ts"]
+    }
+  },
+  "include": ["src"]
+}

package/examples/react/WorkerApp/vite.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vite';
+import { resolve } from 'node:path';
+
+export default defineConfig({
+  root: import.meta.dirname,
+  define: {
+    __MVC_KIT_DEV__: true,
+  },
+  resolve: {
+    alias: {
+      'mvc-kit/react': resolve(import.meta.dirname, '../../../src/react/index.ts'),
+      'mvc-kit': resolve(import.meta.dirname, '../../../src/index.ts'),
+    },
+  },
+  server: {
+    port: 3002,
+  },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mvc-kit",
-  "version": "2.12.5",
+  "version": "2.13.1",
   "description": "Zero-magic, class-based reactive ViewModel library",
   "type": "module",
   "main": "./dist/mvc-kit.cjs",
@@ -64,9 +64,11 @@
   "files": [
     "./mvc-kit-logo.jpg",
     "dist",
+    "examples",
     "src",
     "agent-config",
-    "README.md"
+    "README.md",
+    "BEST_PRACTICES.md"
   ],
   "bin": {
     "mvc-kit-setup": "./agent-config/bin/setup.mjs"
@@ -81,16 +83,16 @@
   },
   "devDependencies": {
     "@testing-library/react": "^16.0.0",
-    "@types/react": "^18.3.0",
-    "esbuild": "^0.25.12",
+    "@types/react": "^19.2.14",
+    "esbuild": "^0.28.0",
     "fake-indexeddb": "^6.2.5",
-    "jsdom": "^26.0.0",
+    "jsdom": "^29.0.2",
     "msw": "^2.12.10",
-    "react": "^18.3.0",
-    "react-dom": "^18.3.0",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
     "react-router-dom": "^7.0.0",
-    "typescript": "~5.9.3",
-    "vite": "^7.3.1",
+    "typescript": "~6.0.2",
+    "vite": "^8.0.8",
     "vitest": "^4.0.18"
   }
 }

package/src/Pending.test.ts

@@ -1510,8 +1510,7 @@ describe('Pending', () => {
 
     it('supersede replaces meta', async () => {
       const p = new Pending<string, TestMeta>();
-      let resolve1!: () => void;
-      const promise1 = new Promise<void>(r => { resolve1 = r; });
+      const promise1 = new Promise<void>(() => {});
 
       p.enqueue('a', 'send', () => promise1, { label: 'first', priority: 1 });
       await vi.advanceTimersByTimeAsync(0);

package/src/Sorting.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi } from 'vitest';
 import { Sorting } from './Sorting';
 import type { SortDescriptor } from './Sorting';
 import { ViewModel } from './ViewModel';

package/src/produceDraft.test.ts

@@ -143,7 +143,7 @@ describe('produceDraft', () => {
   // ── Original immutability ───────────────────────────────────────
 
   it('never mutates original state', () => {
-    const state = Object.freeze({ count: 0, name: 'test' });
+    const state = Object.freeze<{ count: number; name: string }>({ count: 0, name: 'test' });
     const result = produceDraft(state, (d) => {
       d.count = 5;
       d.name = 'updated';
@@ -154,8 +154,8 @@ describe('produceDraft', () => {
   });
 
   it('never mutates original nested objects', () => {
-    const config = Object.freeze({ theme: 'dark', size: 14 });
-    const state = Object.freeze({ config });
+    const config = { theme: 'dark', size: 14 };
+    const state = Object.freeze<{ config: { theme: string; size: number } }>({ config });
     const result = produceDraft(state, (d) => {
       d.config.theme = 'light';
     });

package/src/react/components/CardList.test.tsx

@@ -59,7 +59,7 @@ describe('CardList', () => {
   });
 
   it('uses custom keyOf', () => {
-    const { container } = render(
+    render(
       <CardList
         items={[{ uid: 'x', label: 'X' }]}
         keyOf={(item: any) => item.uid}

package/src/react/components/DataTable.test.tsx

@@ -411,7 +411,7 @@ describe('DataTable', () => {
         <DataTable
           items={users.slice(0, 1)}
           columns={columns}
-          renderRow={(item, index, cells) => (
+          renderRow={(_item, _index, cells) => (
             <>{cells}<td data-testid="extra">Extra</td></>
           )}
         />,