mvc-kit 2.12.5 → 2.13.1

package/examples/primitive/trackable.ts

@@ -0,0 +1,225 @@
+import { Trackable, ViewModel, bindPublicMethods } from 'mvc-kit';
+
+// Trackable: Base class for custom reactive objects
+//
+// Provides the subscribable + disposable + auto-bind foundation that
+// all composable helpers (Sorting, Selection, Feed, Pagination, Pending)
+// are built on. Extend it to build your own reactive objects that
+// integrate with ViewModel's auto-tracking system.
+//
+// What Trackable provides:
+//   - subscribe() / notify() for change notifications
+//   - dispose() / disposeSignal / addCleanup() for lifecycle
+//   - Auto-bound public methods (point-free callbacks)
+//
+// What Trackable does NOT provide:
+//   - State management (no set(), no state getter)
+//   - Computed getters / memoization
+//   - Async tracking (no vm.async)
+//   - init() lifecycle (implement Initializable yourself if needed)
+
+// --- Example 1: Custom RPC query wrapper ---
+
+interface RPCResponse<T> {
+  data: T;
+  success: boolean;
+  code: number;
+}
+
+class RPCQuery<Args, Data> extends Trackable {
+  private _data: Data | undefined = undefined;
+  private _loading = false;
+  private _error: string | null = null;
+  private _callCounter = 0;
+
+  // Computed getters — auto-tracked when read inside ViewModel getters
+  get data(): Data | undefined { return this._data; }
+  get loading(): boolean { return this._loading; }
+  get error(): string | null { return this._error; }
+
+  constructor(private _endpoint: string) {
+    super();
+  }
+
+  async call(args?: Args): Promise<RPCResponse<Data>> {
+    if (this.disposed) throw new Error('RPCQuery: call() after dispose');
+
+    const callId = ++this._callCounter;
+    this._loading = true;
+    this._error = null;
+    this.notify();
+
+    try {
+      // Simulate an RPC call
+      const response = await simulateRPC<Data>(this._endpoint, args);
+
+      // Stale-call guard: only apply if this is still the latest call
+      if (!this.disposed && callId === this._callCounter) {
+        this._data = response.data;
+        this._loading = false;
+        this._error = null;
+        this.notify();
+      }
+
+      return response;
+    } catch (err) {
+      if (!this.disposed && callId === this._callCounter) {
+        this._loading = false;
+        this._error = (err as Error).message;
+        this.notify();
+      }
+      throw err;
+    }
+  }
+
+  clear() {
+    this._data = undefined;
+    this._error = null;
+    this.notify();
+  }
+}
+
+// Simulate RPC
+async function simulateRPC<T>(_endpoint: string, _args?: unknown): Promise<RPCResponse<T>> {
+  await new Promise(r => setTimeout(r, 100));
+  return { data: [{ id: '1', name: 'Alice' }, { id: '2', name: 'Bob' }] as T, success: true, code: 200 };
+}
+
+// --- Basic usage ---
+
+const query = new RPCQuery<{ search: string }, { id: string; name: string }[]>('Users.Search');
+
+// Subscribe to changes
+query.subscribe(() => {
+  console.log(`Query state: loading=${query.loading}, data=${query.data?.length ?? 0} items, error=${query.error}`);
+});
+
+console.log('Loading:', query.loading); // false
+console.log('Data:', query.data);       // undefined
+
+await query.call({ search: 'alice' });
+// Query state: loading=true, data=0 items, error=null
+// Query state: loading=false, data=2 items, error=null
+
+console.log('Data after call:', query.data); // [{ id: '1', name: 'Alice' }, ...]
+
+// --- Method binding (point-free) ---
+
+const { call, clear, dispose } = query;
+// These work without wrapper functions — auto-bound by Trackable
+clear(); // Resets data
+
+// --- Dispose lifecycle ---
+
+console.log('Disposed:', query.disposed);          // false
+console.log('Signal aborted:', query.disposeSignal.aborted); // false
+
+dispose();
+
+console.log('Disposed:', query.disposed);          // true
+console.log('Signal aborted:', query.disposeSignal.aborted); // true
+
+// --- Example 2: ViewModel auto-tracking integration ---
+
+interface User {
+  id: string;
+  name: string;
+}
+
+class UsersViewModel extends ViewModel {
+  // RPCQuery as a property — auto-tracked by ViewModel's dependency system
+  readonly users = new RPCQuery<void, User[]>('Users.List');
+
+  // This getter auto-invalidates when users.notify() fires
+  get userCount(): number {
+    return this.users.data?.length ?? 0;
+  }
+
+  get isLoading(): boolean {
+    return this.users.loading;
+  }
+
+  get userNames(): string[] {
+    return (this.users.data ?? []).map(u => u.name);
+  }
+
+  async onInit() {
+    await this.users.call();
+  }
+}
+
+const vm = new UsersViewModel();
+vm.init();
+
+// After init, the RPCQuery fires and getters update automatically
+await new Promise(r => setTimeout(r, 200));
+
+console.log('User count:', vm.userCount); // 2
+console.log('User names:', vm.userNames); // ['Alice', 'Bob']
+
+vm.dispose();
+
+// --- Example 3: addCleanup for external subscriptions ---
+
+class LivePrice extends Trackable {
+  private _price = 0;
+
+  get price(): number { return this._price; }
+
+  constructor(symbol: string) {
+    super();
+
+    // Simulate a WebSocket price subscription
+    const interval = setInterval(() => {
+      this._price = Math.round(Math.random() * 10000) / 100;
+      this.notify();
+    }, 1000);
+
+    // addCleanup runs on dispose — auto-cleanup
+    this.addCleanup(() => {
+      clearInterval(interval);
+      console.log(`Unsubscribed from ${symbol} price feed`);
+    });
+  }
+
+  protected onDispose() {
+    console.log('LivePrice disposed');
+  }
+}
+
+const btcPrice = new LivePrice('BTC');
+
+const unsub = btcPrice.subscribe(() => {
+  console.log(`BTC: $${btcPrice.price}`);
+});
+
+// Let it tick a couple times
+await new Promise(r => setTimeout(r, 2500));
+
+btcPrice.dispose(); // Clears interval, logs "Unsubscribed...", logs "LivePrice disposed"
+unsub(); // Safe to call after dispose — no-op
+
+// --- Example 4: bindPublicMethods standalone utility ---
+//
+// For classes that don't extend Trackable but still want point-free methods.
+
+class Formatter {
+  constructor(private locale: string) {
+    bindPublicMethods(this);
+  }
+
+  formatCurrency(amount: number): string {
+    return new Intl.NumberFormat(this.locale, { style: 'currency', currency: 'USD' }).format(amount);
+  }
+
+  formatDate(date: Date): string {
+    return new Intl.DateTimeFormat(this.locale).format(date);
+  }
+}
+
+const fmt = new Formatter('en-US');
+
+// Destructured methods work — bound by bindPublicMethods
+const { formatCurrency, formatDate } = fmt;
+console.log(formatCurrency(1234.56));       // $1,234.56
+console.log(formatDate(new Date(2025, 0, 1))); // 1/1/2025

package/examples/primitive/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "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"]
+    }
+  },
+  "include": ["."]
+}

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}</>;
+}