mvc-kit 2.12.5 → 2.13.1

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>,
+);

package/examples/react/AuthExample/src/mock/api.ts

@@ -0,0 +1,78 @@
+import { HttpError } from 'mvc-kit';
+import type { AuthUser, AuthResponse } from '../types/auth';
+
+function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new DOMException('Aborted', 'AbortError'));
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => {
+      clearTimeout(timer);
+      reject(new DOMException('Aborted', 'AbortError'));
+    }, { once: true });
+  });
+}
+
+async function mockFetch<T>(data: T, ms?: number, signal?: AbortSignal): Promise<T> {
+  const jitter = 300 + Math.random() * 400;
+  await delay(ms ?? jitter, signal);
+  return data;
+}
+
+const USERS: AuthUser[] = [
+  { id: '1', name: 'Alice Admin', email: 'admin@example.com', role: 'admin', createdAt: '2024-01-15T08:00:00Z' },
+  { id: '2', name: 'Maya Manager', email: 'manager@example.com', role: 'manager', createdAt: '2024-03-22T10:30:00Z' },
+  { id: '3', name: 'Uma User', email: 'user@example.com', role: 'member', createdAt: '2024-06-10T14:15:00Z' },
+];
+
+const TOKEN_MAP = new Map<string, AuthUser>();
+let nextTokenId = 1;
+
+function findUser(email: string): AuthUser | undefined {
+  return USERS.find(u => u.email === email);
+}
+
+export async function mockLogin(email: string, password: string, signal?: AbortSignal): Promise<AuthResponse> {
+  const user = findUser(email);
+  if (!user || password !== 'password') {
+    throw await mockFetch(new HttpError(401, 'Invalid email or password'), 200, signal);
+  }
+  const accessToken = `tok_${nextTokenId++}_${user.id}`;
+  TOKEN_MAP.set(accessToken, user);
+  return mockFetch({ user, accessToken }, undefined, signal);
+}
+
+export async function mockRegister(name: string, email: string, password: string, signal?: AbortSignal): Promise<AuthResponse> {
+  if (findUser(email)) {
+    throw await mockFetch(new HttpError(409, 'Email already registered'), 200, signal);
+  }
+  if (password.length < 6) {
+    throw await mockFetch(new HttpError(400, 'Password must be at least 6 characters'), 200, signal);
+  }
+  const user: AuthUser = {
+    id: String(USERS.length + 1),
+    name,
+    email,
+    role: 'member',
+    createdAt: new Date().toISOString(),
+  };
+  USERS.push(user);
+  const accessToken = `tok_${nextTokenId++}_${user.id}`;
+  TOKEN_MAP.set(accessToken, user);
+  return mockFetch({ user, accessToken }, undefined, signal);
+}
+
+export async function mockGetProfile(token: string, signal?: AbortSignal): Promise<AuthUser> {
+  const user = TOKEN_MAP.get(token);
+  if (!user) {
+    throw await mockFetch(new HttpError(401, 'Invalid or expired token'), 100, signal);
+  }
+  return mockFetch({ ...user }, undefined, signal);
+}
+
+export async function mockLogout(token: string, signal?: AbortSignal): Promise<void> {
+  TOKEN_MAP.delete(token);
+  await mockFetch(undefined, 200, signal);
+}

package/examples/react/AuthExample/src/models/LoginFormModel.ts

@@ -0,0 +1,19 @@
+import { Model } from 'mvc-kit';
+import type { ValidationErrors } from 'mvc-kit';
+
+export interface LoginFormState {
+  email: string;
+  password: string;
+}
+
+export class LoginFormModel extends Model<LoginFormState> {
+  setEmail(email: string) { this.set({ email }); }
+  setPassword(password: string) { this.set({ password }); }
+
+  protected validate(state: LoginFormState): ValidationErrors<LoginFormState> {
+    const errors: Partial<Record<keyof LoginFormState, string>> = {};
+    if (!state.email.includes('@')) errors.email = 'Valid email required';
+    if (state.password.length < 6) errors.password = 'Must be at least 6 characters';
+    return errors;
+  }
+}

package/examples/react/AuthExample/src/models/RegisterFormModel.ts

@@ -0,0 +1,25 @@
+import { Model } from 'mvc-kit';
+import type { ValidationErrors } from 'mvc-kit';
+
+export interface RegisterFormState {
+  name: string;
+  email: string;
+  password: string;
+  confirmPassword: string;
+}
+
+export class RegisterFormModel extends Model<RegisterFormState> {
+  setName(name: string) { this.set({ name }); }
+  setEmail(email: string) { this.set({ email }); }
+  setPassword(password: string) { this.set({ password }); }
+  setConfirmPassword(confirmPassword: string) { this.set({ confirmPassword }); }
+
+  protected validate(state: RegisterFormState): ValidationErrors<RegisterFormState> {
+    const errors: Partial<Record<keyof RegisterFormState, string>> = {};
+    if (state.name.trim().length < 2) errors.name = 'Name is required';
+    if (!state.email.includes('@')) errors.email = 'Valid email required';
+    if (state.password.length < 6) errors.password = 'Must be at least 6 characters';
+    if (state.confirmPassword !== state.password) errors.confirmPassword = 'Passwords do not match';
+    return errors;
+  }
+}

package/examples/react/AuthExample/src/services/AuthService.ts

@@ -0,0 +1,21 @@
+import { Service } from 'mvc-kit';
+import type { AuthUser, AuthResponse } from '../types/auth';
+import { mockLogin, mockRegister, mockGetProfile, mockLogout } from '../mock/api';
+
+export class AuthService extends Service {
+  login(email: string, password: string, signal?: AbortSignal): Promise<AuthResponse> {
+    return mockLogin(email, password, signal);
+  }
+
+  register(name: string, email: string, password: string, signal?: AbortSignal): Promise<AuthResponse> {
+    return mockRegister(name, email, password, signal);
+  }
+
+  getProfile(token: string, signal?: AbortSignal): Promise<AuthUser> {
+    return mockGetProfile(token, signal);
+  }
+
+  logout(token: string, signal?: AbortSignal): Promise<void> {
+    return mockLogout(token, signal);
+  }
+}