mvc-kit 2.13.0 → 2.13.1

package/examples/primitive/viewmodel-service.ts

@@ -0,0 +1,161 @@
+import {
+  ViewModel,
+  Service,
+  Collection,
+  HttpError,
+  isAbortError,
+  singleton,
+  teardownAll,
+} from 'mvc-kit';
+
+// ViewModel + Service + Collection: Full data-loading pattern
+//
+// This example shows the typical data-loading architecture:
+//   - Service: Stateless HTTP adapter (wraps fetch with HttpError handling)
+//   - Collection: Shared reactive data cache (singleton)
+//   - ViewModel: Orchestrates loading, holds UI state, provides computed getters
+//
+// The ViewModel's async methods are automatically tracked — access
+// loading/error state via vm.async.methodName without manual flags.
+
+// --- Entity type ---
+
+interface User {
+  id: string;
+  name: string;
+  role: 'admin' | 'member';
+}
+
+// --- Service ---
+
+class UserService extends Service {
+  async getAll(signal?: AbortSignal): Promise<User[]> {
+    // Simulated API call — in production this would be fetch()
+    await delay(500, signal);
+    return [
+      { id: '1', name: 'Alice', role: 'admin' },
+      { id: '2', name: 'Bob', role: 'member' },
+      { id: '3', name: 'Carol', role: 'member' },
+    ];
+  }
+
+  async save(user: User, signal?: AbortSignal): Promise<User> {
+    await delay(300, signal);
+    if (!user.name.trim()) throw new HttpError(400, 'Name is required');
+    return user;
+  }
+}
+
+// --- Collection ---
+
+class UsersCollection extends Collection<User> {}
+
+// --- ViewModel ---
+
+interface UsersState {
+  items: User[];
+  search: string;
+}
+
+class UsersViewModel extends ViewModel<UsersState> {
+  private service = singleton(UserService);
+  private collection = singleton(UsersCollection);
+
+  // --- Computed getters ---
+  get filtered(): User[] {
+    const { items, search } = this.state;
+    if (!search) return items;
+    const q = search.toLowerCase();
+    return items.filter(u => u.name.toLowerCase().includes(q));
+  }
+
+  get total(): number {
+    return this.state.items.length;
+  }
+
+  get adminCount(): number {
+    return this.state.items.filter(u => u.role === 'admin').length;
+  }
+
+  // --- Lifecycle ---
+  protected onInit() {
+    this.subscribeTo(this.collection, () => {
+      this.set({ items: this.collection.items as User[] });
+    });
+
+    if (this.collection.length > 0) {
+      this.set({ items: this.collection.items as User[] });
+    } else {
+      this.load();
+    }
+  }
+
+  // --- Actions ---
+  async load() {
+    const data = await this.service.getAll(this.disposeSignal);
+    this.collection.reset(data);
+  }
+
+  async save(user: User) {
+    try {
+      const saved = await this.service.save(user, this.disposeSignal);
+      this.collection.update(saved.id, saved);
+    } catch (e) {
+      if (!isAbortError(e)) {
+        console.error('Save failed:', (e as Error).message);
+      }
+      throw e; // re-throw so async tracking captures it
+    }
+  }
+
+  // --- Setters ---
+  setSearch(search: string) {
+    this.set({ search });
+  }
+}
+
+// --- Usage ---
+
+const vm = new UsersViewModel({ items: [], search: '' });
+vm.init(); // activates getter memoization + async tracking
+
+// Async tracking — no manual loading/error state needed
+console.log('Loading:', vm.async.load.loading); // true (load started in onInit)
+
+await vm.load();
+
+console.log('Loading:', vm.async.load.loading); // false
+console.log('Error:', vm.async.load.error); // null
+console.log('Total users:', vm.total); // 3
+console.log('Admins:', vm.adminCount); // 1
+
+// Computed getters recompute when state changes
+vm.setSearch('alice');
+console.log('Filtered:', vm.filtered.length); // 1
+
+vm.setSearch('');
+console.log('Filtered:', vm.filtered.length); // 3
+
+// Cleanup
+vm.dispose();
+teardownAll();
+
+// --- Helper ---
+
+function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+      },
+      { once: true },
+    );
+  });
+}

package/examples/react/AuthExample/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>mvc-kit Auth Example</title>
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="/src/main.tsx"></script>
+</body>
+</html>

package/examples/react/AuthExample/src/App.tsx

@@ -0,0 +1,29 @@
+import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom';
+import { AuthGuard } from './components/AuthGuard';
+import { AppHeader } from './components/AppHeader';
+import { DashboardPage } from './components/DashboardPage';
+import { ProfilePage } from './components/ProfilePage';
+import { AdminPage } from './components/AdminPage';
+import { Toast } from './components/Toast';
+
+export function App() {
+  return (
+    <BrowserRouter>
+      {/* AuthGuard wraps all authenticated content via composition.
+          When not authenticated, it shows the login/register screen
+          WITHOUT redirecting — preserving the current URL and any
+          query params. After login, children render immediately
+          at the original URL. */}
+      <AuthGuard>
+        <AppHeader />
+        <Routes>
+          <Route path="/" element={<DashboardPage />} />
+          <Route path="/profile" element={<ProfilePage />} />
+          <Route path="/admin" element={<AdminPage />} />
+          <Route path="*" element={<Navigate to="/" replace />} />
+        </Routes>
+      </AuthGuard>
+      <Toast />
+    </BrowserRouter>
+  );
+}

package/examples/react/AuthExample/src/components/AdminPage.tsx

@@ -0,0 +1,51 @@
+import { useSingleton } from 'mvc-kit/react';
+import { AuthViewModel } from '../viewmodels/AuthViewModel';
+
+export function AdminPage() {
+  const [state, vm] = useSingleton(AuthViewModel);
+
+  // Role check is done inside the page, not via a route wrapper.
+  // This keeps routing simple and the access-denied message inline.
+  if (!vm.isAdmin) {
+    return (
+      <div className="page-content">
+        <div className="access-denied">
+          <h2>Access Denied</h2>
+          <p>
+            You are signed in as <strong>{vm.displayName}</strong> with
+            the <span className={`badge badge-${state.user!.role}`}>{state.user!.role}</span> role.
+          </p>
+          <p>This page requires the <span className="badge badge-admin">admin</span> role.</p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="page-content">
+      <h1 className="page-title">Admin Panel</h1>
+
+      <div className="card" style={{ marginBottom: '1rem' }}>
+        <h3 style={{ marginBottom: '0.5rem' }}>System Status</h3>
+        <div className="stats-grid">
+          <div className="stat-card">
+            <div className="stat-label">Active Users</div>
+            <div className="stat-value">3</div>
+          </div>
+          <div className="stat-card">
+            <div className="stat-label">Auth Tokens</div>
+            <div className="stat-value">1</div>
+          </div>
+        </div>
+      </div>
+
+      <div className="card">
+        <h3 style={{ marginBottom: '0.5rem' }}>Admin-Only Content</h3>
+        <p style={{ color: 'var(--color-text-secondary)' }}>
+          This content is only visible to users with the admin role.
+          The role check happens inside the page component, not at the route level.
+        </p>
+      </div>
+    </div>
+  );
+}

package/examples/react/AuthExample/src/components/AppHeader.tsx

@@ -0,0 +1,32 @@
+import { NavLink } from 'react-router-dom';
+import { useSingleton } from 'mvc-kit/react';
+import { AuthViewModel } from '../viewmodels/AuthViewModel';
+
+export function AppHeader() {
+  const [, vm] = useSingleton(AuthViewModel);
+
+  return (
+    <header className="app-header">
+      <nav className="header-nav">
+        <span className="header-logo">mvc-kit Auth</span>
+        <NavLink to="/" end className={({ isActive }) => `header-link ${isActive ? 'active' : ''}`}>
+          Dashboard
+        </NavLink>
+        <NavLink to="/profile" className={({ isActive }) => `header-link ${isActive ? 'active' : ''}`}>
+          Profile
+        </NavLink>
+        <NavLink to="/admin" className={({ isActive }) => `header-link ${isActive ? 'active' : ''}`}>
+          Admin
+        </NavLink>
+      </nav>
+
+      <div className="header-user">
+        <div className="avatar">{vm.initials}</div>
+        <span className="header-user-name">{vm.displayName}</span>
+        <button type="button" className="btn btn-secondary btn-sm" onClick={vm.logout}>
+          Logout
+        </button>
+      </div>
+    </header>
+  );
+}

package/examples/react/AuthExample/src/components/AuthGuard.tsx

@@ -0,0 +1,50 @@
+import type { ReactNode } from 'react';
+import { useSingleton } from 'mvc-kit/react';
+import { AuthViewModel } from '../viewmodels/AuthViewModel';
+import { AuthScreen } from './AuthScreen';
+
+/**
+ * AuthGuard — composition-based authentication wrapper.
+ *
+ * Instead of using <ProtectedRoute> wrappers or redirect-based guards,
+ * this component wraps the entire authenticated app via composition:
+ *
+ *   <AuthGuard>
+ *     <AppHeader />
+ *     <Routes>...</Routes>
+ *   </AuthGuard>
+ *
+ * How it works:
+ * - Reads auth state from the singleton AuthViewModel
+ * - While restoring a session (onInit loading), shows a spinner
+ * - When not authenticated, renders <AuthScreen /> (login/register UI)
+ *   WITHOUT navigating away — the current URL and query params are preserved
+ * - When authenticated, renders {children} immediately at the current URL
+ *
+ * Benefits over redirect-based auth:
+ * - URL is always preserved — no redirect loops, no lost query params
+ * - No coupling between auth state and router configuration
+ * - Children mount immediately after login with no extra navigation
+ * - Simpler mental model: auth state controls what renders, not where you navigate
+ */
+export function AuthGuard({ children }: { children: ReactNode }) {
+  const [, vm] = useSingleton(AuthViewModel);
+
+  // Session restore in progress — show a loading indicator
+  if (vm.async.onInit.loading) {
+    return (
+      <div className="auth-loading">
+        <div className="spinner spinner-lg" />
+        <p>Restoring session...</p>
+      </div>
+    );
+  }
+
+  // Not authenticated — show login/register UI in place (no redirect)
+  if (!vm.isAuthenticated) {
+    return <AuthScreen />;
+  }
+
+  // Authenticated — render the app
+  return <>{children}</>;
+}

package/examples/react/AuthExample/src/components/AuthScreen.tsx

@@ -0,0 +1,181 @@
+import { useState } from 'react';
+import { useSingleton, useModel } from 'mvc-kit/react';
+import { AuthViewModel } from '../viewmodels/AuthViewModel';
+import { LoginFormModel } from '../models/LoginFormModel';
+import { RegisterFormModel } from '../models/RegisterFormModel';
+
+type AuthView = 'login' | 'register';
+
+export function AuthScreen() {
+  // Ephemeral UI state — which form to show. This is acceptable as plain useState
+  // because it's purely presentational (not domain state).
+  const [view, setView] = useState<AuthView>('login');
+
+  return (
+    <div className="auth-page">
+      <div className="auth-card">
+        <h1 className="auth-title">mvc-kit Auth</h1>
+        {view === 'login' ? (
+          <LoginView onSwitchToRegister={() => setView('register')} />
+        ) : (
+          <RegisterView onSwitchToLogin={() => setView('login')} />
+        )}
+      </div>
+    </div>
+  );
+}
+
+function LoginView({ onSwitchToRegister }: { onSwitchToRegister: () => void }) {
+  const [, authVM] = useSingleton(AuthViewModel);
+  const { loading, error } = authVM.async.login;
+  const { state, errors, valid, dirty, model } = useModel(
+    () => new LoginFormModel({ email: '', password: '' }),
+  );
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!valid) return;
+    authVM.login(state.email, state.password);
+  };
+
+  return (
+    <>
+      <p className="auth-subtitle">
+        Sign in with <code>admin@example.com</code>, <code>manager@example.com</code>,
+        or <code>user@example.com</code> (password: <code>password</code>)
+      </p>
+
+      {error && <div className="error-banner">{error}</div>}
+
+      <form onSubmit={handleSubmit}>
+        <div className="form-group">
+          <label className="form-label">Email</label>
+          <input
+            className={`form-input ${errors.email && dirty ? 'error' : ''}`}
+            type="text"
+            value={state.email}
+            onChange={e => model.setEmail(e.target.value)}
+            placeholder="admin@example.com"
+          />
+          {errors.email && dirty && <div className="form-error">{errors.email}</div>}
+        </div>
+
+        <div className="form-group">
+          <label className="form-label">Password</label>
+          <input
+            className={`form-input ${errors.password && dirty ? 'error' : ''}`}
+            type="password"
+            value={state.password}
+            onChange={e => model.setPassword(e.target.value)}
+            placeholder="6+ characters"
+          />
+          {errors.password && dirty && <div className="form-error">{errors.password}</div>}
+        </div>
+
+        <button
+          type="submit"
+          className="btn btn-primary"
+          style={{ width: '100%', marginTop: '0.5rem' }}
+          disabled={!valid || loading}
+        >
+          {loading ? 'Signing in...' : 'Sign In'}
+        </button>
+      </form>
+
+      <p className="auth-toggle">
+        Don't have an account?{' '}
+        <button type="button" className="link" onClick={onSwitchToRegister}>
+          Register
+        </button>
+      </p>
+    </>
+  );
+}
+
+function RegisterView({ onSwitchToLogin }: { onSwitchToLogin: () => void }) {
+  const [, authVM] = useSingleton(AuthViewModel);
+  const { loading, error } = authVM.async.register;
+  const { state, errors, valid, dirty, model } = useModel(
+    () => new RegisterFormModel({ name: '', email: '', password: '', confirmPassword: '' }),
+  );
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!valid) return;
+    authVM.register(state.name, state.email, state.password);
+  };
+
+  return (
+    <>
+      <p className="auth-subtitle">Create a new account</p>
+
+      {error && <div className="error-banner">{error}</div>}
+
+      <form onSubmit={handleSubmit}>
+        <div className="form-group">
+          <label className="form-label">Name</label>
+          <input
+            className={`form-input ${errors.name && dirty ? 'error' : ''}`}
+            type="text"
+            value={state.name}
+            onChange={e => model.setName(e.target.value)}
+            placeholder="Your name"
+          />
+          {errors.name && dirty && <div className="form-error">{errors.name}</div>}
+        </div>
+
+        <div className="form-group">
+          <label className="form-label">Email</label>
+          <input
+            className={`form-input ${errors.email && dirty ? 'error' : ''}`}
+            type="text"
+            value={state.email}
+            onChange={e => model.setEmail(e.target.value)}
+            placeholder="you@example.com"
+          />
+          {errors.email && dirty && <div className="form-error">{errors.email}</div>}
+        </div>
+
+        <div className="form-group">
+          <label className="form-label">Password</label>
+          <input
+            className={`form-input ${errors.password && dirty ? 'error' : ''}`}
+            type="password"
+            value={state.password}
+            onChange={e => model.setPassword(e.target.value)}
+            placeholder="6+ characters"
+          />
+          {errors.password && dirty && <div className="form-error">{errors.password}</div>}
+        </div>
+
+        <div className="form-group">
+          <label className="form-label">Confirm Password</label>
+          <input
+            className={`form-input ${errors.confirmPassword && dirty ? 'error' : ''}`}
+            type="password"
+            value={state.confirmPassword}
+            onChange={e => model.setConfirmPassword(e.target.value)}
+            placeholder="Repeat password"
+          />
+          {errors.confirmPassword && dirty && <div className="form-error">{errors.confirmPassword}</div>}
+        </div>
+
+        <button
+          type="submit"
+          className="btn btn-primary"
+          style={{ width: '100%', marginTop: '0.5rem' }}
+          disabled={!valid || loading}
+        >
+          {loading ? 'Creating account...' : 'Register'}
+        </button>
+      </form>
+
+      <p className="auth-toggle">
+        Already have an account?{' '}
+        <button type="button" className="link" onClick={onSwitchToLogin}>
+          Sign in
+        </button>
+      </p>
+    </>
+  );
+}

package/examples/react/AuthExample/src/components/DashboardPage.tsx

@@ -0,0 +1,41 @@
+import { useSingleton } from 'mvc-kit/react';
+import { AuthViewModel } from '../viewmodels/AuthViewModel';
+
+export function DashboardPage() {
+  const [state, vm] = useSingleton(AuthViewModel);
+
+  return (
+    <div className="page-content">
+      <h1 className="page-title">Dashboard</h1>
+
+      <div className="card" style={{ marginBottom: '1.5rem' }}>
+        <h2 style={{ marginBottom: '0.5rem' }}>Welcome, {vm.displayName}!</h2>
+        <p style={{ color: 'var(--color-text-secondary)' }}>
+          You are signed in as <strong>{state.user!.email}</strong> with
+          the <span className={`badge badge-${state.user!.role}`}>{state.user!.role}</span> role.
+        </p>
+      </div>
+
+      <div className="stats-grid">
+        <div className="stat-card">
+          <div className="stat-label">Role</div>
+          <div className="stat-value" style={{ fontSize: '1.25rem' }}>{vm.userRole}</div>
+        </div>
+        <div className="stat-card">
+          <div className="stat-label">Admin Access</div>
+          <div className="stat-value" style={{ fontSize: '1.25rem' }}>{vm.isAdmin ? 'Yes' : 'No'}</div>
+        </div>
+      </div>
+
+      <div className="card">
+        <h3 style={{ marginBottom: '0.75rem' }}>Auth Pattern Highlights</h3>
+        <ul style={{ paddingLeft: '1.25rem', color: 'var(--color-text-secondary)', lineHeight: 1.8 }}>
+          <li><code>isAuthenticated</code> is a getter (derived from state), not stored state</li>
+          <li>Session restored via <code>onInit()</code>, not useEffect</li>
+          <li><code>&lt;AuthGuard&gt;</code> uses composition — no redirects, URL preserved</li>
+          <li>Navigate to <code>/admin</code> to see role-based access (inline, not route-guarded)</li>
+        </ul>
+      </div>
+    </div>
+  );
+}

package/examples/react/AuthExample/src/components/ProfilePage.tsx

@@ -0,0 +1,44 @@
+import { useSingleton } from 'mvc-kit/react';
+import { AuthViewModel } from '../viewmodels/AuthViewModel';
+
+export function ProfilePage() {
+  const [state, vm] = useSingleton(AuthViewModel);
+  const user = state.user!;
+
+  return (
+    <div className="page-content">
+      <h1 className="page-title">Profile</h1>
+
+      <div className="card profile-card">
+        <div className="profile-header">
+          <div className="avatar avatar-lg">{vm.initials}</div>
+          <div>
+            <h2>{vm.displayName}</h2>
+            <p style={{ color: 'var(--color-text-secondary)' }}>{user.email}</p>
+          </div>
+        </div>
+
+        <div className="profile-details">
+          <div className="detail-row">
+            <span className="detail-label">Role</span>
+            <span className={`badge badge-${user.role}`}>{user.role}</span>
+          </div>
+          <div className="detail-row">
+            <span className="detail-label">Member Since</span>
+            <span>{new Date(user.createdAt).toLocaleDateString()}</span>
+          </div>
+          <div className="detail-row">
+            <span className="detail-label">User ID</span>
+            <span style={{ fontFamily: 'monospace' }}>{user.id}</span>
+          </div>
+        </div>
+
+        <div style={{ marginTop: '1.5rem' }}>
+          <button type="button" className="btn btn-danger" onClick={vm.logout}>
+            Logout
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/examples/react/AuthExample/src/components/Toast.tsx

@@ -0,0 +1,41 @@
+import { useState, useCallback } from 'react';
+import { useSingleton } from 'mvc-kit/react';
+import { useEvent } from 'mvc-kit/react';
+import { AppEventBus } from '../events/AppEventBus';
+
+interface ToastItem {
+  id: number;
+  message: string;
+  severity: 'success' | 'error' | 'info';
+}
+
+let nextId = 0;
+
+export function Toast() {
+  const bus = useSingleton(AppEventBus);
+  const [toasts, setToasts] = useState<ToastItem[]>([]);
+
+  const addToast = useCallback((item: Omit<ToastItem, 'id'>) => {
+    const id = nextId++;
+    setToasts(prev => [...prev, { ...item, id }]);
+    setTimeout(() => {
+      setToasts(prev => prev.filter(t => t.id !== id));
+    }, 3000);
+  }, []);
+
+  useEvent(bus, 'toast:show', ({ message, severity }) => {
+    addToast({ message, severity });
+  });
+
+  if (toasts.length === 0) return null;
+
+  return (
+    <div className="toast-container">
+      {toasts.map(t => (
+        <div key={t.id} className={`toast toast-${t.severity}`}>
+          {t.message}
+        </div>
+      ))}
+    </div>
+  );
+}

package/examples/react/AuthExample/src/env.d.ts

@@ -0,0 +1,10 @@
+declare const __MVC_KIT_DEV__: boolean;
+
+declare module 'react-dom/client' {
+  import type { ReactNode } from 'react';
+  interface Root {
+    render(children: ReactNode): void;
+    unmount(): void;
+  }
+  export function createRoot(container: Element): Root;
+}

package/examples/react/AuthExample/src/events/AppEventBus.ts

@@ -0,0 +1,7 @@
+import { EventBus } from 'mvc-kit';
+
+export interface AppEvents {
+  'toast:show': { message: string; severity: 'success' | 'error' | 'info' };
+}
+
+export class AppEventBus extends EventBus<AppEvents> {}

package/examples/react/AuthExample/src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { App } from './App';
+import './styles.css';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);