mvc-kit 2.12.5 → 2.13.1

package/examples/primitive/controller.ts

@@ -0,0 +1,118 @@
+import { Controller, ViewModel, Collection, singleton, teardownAll } from 'mvc-kit';
+
+// Controller: Stateless multi-ViewModel orchestrator
+//
+// Controllers coordinate between ViewModels, Models, and Services when
+// a single ViewModel can't own the workflow. This is rare — most
+// orchestration fits in a single ViewModel.
+//
+// Use Controller only for pure cross-cutting coordination with no state
+// of its own: multi-step checkout, drag-and-drop between lists, etc.
+//
+// What Controller provides:
+//   - init() / dispose() lifecycle
+//   - subscribeTo() / listenTo() with auto-cleanup
+//   - disposeSignal for cancelling async operations
+//   - addCleanup() for custom teardown
+//
+// What Controller does NOT provide:
+//   - State (no set())
+//   - Computed getters
+//   - Async tracking
+//   - Events (no emit())
+
+// --- Supporting types ---
+
+interface Task {
+  id: string;
+  title: string;
+  status: 'todo' | 'done';
+}
+
+interface TaskListState {
+  items: Task[];
+}
+
+// --- Two ViewModels that the Controller coordinates ---
+
+class TodoListViewModel extends ViewModel<TaskListState> {
+  removeItem(id: string) {
+    this.set({ items: this.state.items.filter(t => t.id !== id) });
+  }
+
+  addItem(task: Task) {
+    this.set({ items: [...this.state.items, task] });
+  }
+}
+
+class DoneListViewModel extends ViewModel<TaskListState> {
+  addItem(task: Task) {
+    this.set({ items: [...this.state.items, { ...task, status: 'done' as const }] });
+  }
+}
+
+// --- Controller definition ---
+
+class TaskTransferController extends Controller {
+  constructor(
+    private todoVM: TodoListViewModel,
+    private doneVM: DoneListViewModel,
+  ) {
+    super();
+  }
+
+  protected onInit() {
+    // subscribeTo auto-cleans up on dispose
+    this.subscribeTo(this.todoVM, (state) => {
+      console.log(`Todo list: ${state.items.length} items`);
+    });
+
+    this.subscribeTo(this.doneVM, (state) => {
+      console.log(`Done list: ${state.items.length} items`);
+    });
+  }
+
+  // Pure coordination — moves an item from todo to done
+  completeTask(taskId: string) {
+    const task = this.todoVM.state.items.find(t => t.id === taskId);
+    if (!task) return;
+    this.todoVM.removeItem(taskId);
+    this.doneVM.addItem(task);
+  }
+
+  protected onDispose() {
+    console.log('TaskTransferController disposed');
+  }
+}
+
+// --- Usage ---
+
+const todoVM = new TodoListViewModel({
+  items: [
+    { id: '1', title: 'Learn mvc-kit', status: 'todo' },
+    { id: '2', title: 'Build an app', status: 'todo' },
+    { id: '3', title: 'Write tests', status: 'todo' },
+  ],
+});
+todoVM.init();
+
+const doneVM = new DoneListViewModel({ items: [] });
+doneVM.init();
+
+const controller = new TaskTransferController(todoVM, doneVM);
+controller.init();
+
+console.log('Todo:', todoVM.state.items.length); // 3
+console.log('Done:', doneVM.state.items.length); // 0
+
+// Controller coordinates the move
+controller.completeTask('1');
+
+console.log('Todo:', todoVM.state.items.length); // 2
+console.log('Done:', doneVM.state.items.length); // 1
+console.log('Done item:', doneVM.state.items[0]?.title); // 'Learn mvc-kit'
+
+// Cleanup
+controller.dispose();
+todoVM.dispose();
+doneVM.dispose();

package/examples/primitive/counter.ts

@@ -0,0 +1,108 @@
+import { ViewModel, singleton, hasSingleton, teardown, teardownAll } from 'mvc-kit';
+
+// ViewModel: Reactive state + computed getters + async tracking + typed events
+//
+// The core building block. Holds state, derives computed values via getters,
+// provides actions to update state, and tracks async method loading/error
+// automatically. After init(), getters are auto-memoized and only recompute
+// when their dependencies change.
+
+// Define state interface
+interface CounterState {
+  count: number;
+}
+
+// Create a ViewModel by extending the base class
+class CounterViewModel extends ViewModel<CounterState> {
+  // --- Computed getters (auto-memoized after init) ---
+  get doubled(): number {
+    return this.state.count * 2;
+  }
+
+  get isPositive(): boolean {
+    return this.state.count > 0;
+  }
+
+  get parity(): 'even' | 'odd' {
+    return this.state.count % 2 === 0 ? 'even' : 'odd';
+  }
+
+  // --- Actions ---
+  increment() {
+    this.set({ count: this.state.count + 1 });
+  }
+
+  decrement() {
+    this.set({ count: this.state.count - 1 });
+  }
+
+  reset() {
+    this.set({ count: 0 });
+  }
+
+  // Updater function pattern for derived updates
+  multiplyBy(factor: number) {
+    this.set(prev => ({ count: prev.count * factor }));
+  }
+
+  // Lifecycle hook: called after each state update
+  protected onSet(prev: Readonly<CounterState>, next: Readonly<CounterState>) {
+    console.log(`Count changed: ${prev.count} → ${next.count}`);
+  }
+
+  // Lifecycle hook: called when disposed
+  protected onDispose() {
+    console.log('CounterViewModel disposed');
+  }
+}
+
+// --- Basic usage ---
+
+const counter = new CounterViewModel({ count: 0 });
+counter.init(); // activates getter memoization and async tracking
+
+// Subscribe to state changes
+const unsubscribe = counter.subscribe((state, prev) => {
+  console.log(`Subscriber notified: ${prev.count} → ${state.count}`);
+});
+
+counter.increment(); // Count changed: 0 → 1
+counter.increment(); // Count changed: 1 → 2
+counter.multiplyBy(5); // Count changed: 2 → 10
+
+// Access current state
+console.log('Current count:', counter.state.count); // 10
+
+// --- Computed getters ---
+
+console.log('Doubled:', counter.doubled); // 20
+console.log('Is positive:', counter.isPositive); // true
+console.log('Parity:', counter.parity); // even
+
+counter.decrement(); // Count changed: 10 → 9
+console.log('Doubled:', counter.doubled); // 18
+console.log('Parity:', counter.parity); // odd
+
+// Cleanup
+unsubscribe();
+counter.dispose();
+
+// --- Singleton pattern ---
+
+// Get or create a singleton instance
+const shared1 = singleton(CounterViewModel, { count: 100 });
+shared1.init(); // activate getter memoization on the singleton too
+const shared2 = singleton(CounterViewModel, { count: 999 }); // args ignored, same instance returned
+
+console.log('Same instance:', shared1 === shared2); // true
+console.log('Singleton count:', shared1.state.count); // 100
+
+// Check if singleton exists
+console.log('Has singleton:', hasSingleton(CounterViewModel)); // true
+
+// Cleanup singleton
+teardown(CounterViewModel);
+console.log('Has singleton after teardown:', hasSingleton(CounterViewModel)); // false
+
+// Cleanup all singletons (useful in tests)
+teardownAll();

package/examples/primitive/env.d.ts

@@ -0,0 +1 @@
+declare const __MVC_KIT_DEV__: boolean;

package/examples/primitive/eventbus.ts

@@ -0,0 +1,77 @@
+import { EventBus } from 'mvc-kit';
+
+// EventBus: Typed pub/sub for decoupled communication
+
+// Define event types
+interface AppEvents {
+  'user:login': { userId: string; timestamp: number };
+  'user:logout': { userId: string };
+  'notification': { message: string; type: 'info' | 'warning' | 'error' };
+  'cart:updated': { itemCount: number };
+}
+
+// --- Basic usage ---
+
+const bus = new EventBus<AppEvents>();
+
+// Subscribe to events
+const unsubLogin = bus.on('user:login', ({ userId, timestamp }) => {
+  console.log(`User ${userId} logged in at ${new Date(timestamp).toISOString()}`);
+});
+
+const unsubNotification = bus.on('notification', ({ message, type }) => {
+  console.log(`[${type.toUpperCase()}] ${message}`);
+});
+
+// Emit events
+bus.emit('user:login', { userId: '123', timestamp: Date.now() });
+bus.emit('notification', { message: 'Welcome back!', type: 'info' });
+
+// One-time subscription - auto-unsubscribes after first event
+bus.once('user:logout', ({ userId }) => {
+  console.log(`User ${userId} logged out (one-time handler)`);
+});
+
+bus.emit('user:logout', { userId: '123' }); // Handler called
+bus.emit('user:logout', { userId: '123' }); // Handler NOT called (already unsubscribed)
+
+// Unsubscribe manually
+unsubLogin();
+unsubNotification();
+
+// After unsubscribe, handlers are not called
+bus.emit('user:login', { userId: '456', timestamp: Date.now() }); // No output
+
+// --- Practical pattern: Cross-component communication ---
+
+class AuthService {
+  constructor(private bus: EventBus<AppEvents>) {}
+
+  login(userId: string) {
+    // ... authentication logic ...
+    this.bus.emit('user:login', { userId, timestamp: Date.now() });
+  }
+
+  logout(userId: string) {
+    // ... logout logic ...
+    this.bus.emit('user:logout', { userId });
+  }
+}
+
+class NotificationManager {
+  constructor(private bus: EventBus<AppEvents>) {
+    // React to login events
+    this.bus.on('user:login', () => {
+      this.bus.emit('notification', { message: 'Welcome!', type: 'info' });
+    });
+  }
+}
+
+// Components can communicate without direct references
+const auth = new AuthService(bus);
+new NotificationManager(bus);
+
+auth.login('789'); // Triggers login event, which triggers notification
+
+// Cleanup
+bus.dispose();

package/examples/primitive/feed.ts

@@ -0,0 +1,162 @@
+import { Feed } from 'mvc-kit';
+
+// Feed: Cursor-based pagination for infinite scroll / load-more
+//
+// A subscribable helper that accumulates items across pages using
+// cursor-based server pagination. Tracks cursor position, hasMore
+// status, and the growing item list.
+//
+// Designed to be a property on a ViewModel — auto-tracked so
+// ViewModel getters that read feed state recompute automatically.
+//
+// Typical flow:
+//   1. ViewModel calls API with feed.cursor
+//   2. API returns { items, hasMore, cursor }
+//   3. ViewModel calls feed.appendPage(result)
+//   4. Repeat until hasMore is false
+
+// --- Entity type ---
+
+interface Post {
+  id: string;
+  title: string;
+  createdAt: string;
+}
+
+// --- Simulated API ---
+
+function fakeFetchPosts(cursor: string | null): {
+  items: Post[];
+  hasMore: boolean;
+  cursor: string;
+} {
+  const pages: Record<string, { items: Post[]; hasMore: boolean; cursor: string }> = {
+    initial: {
+      items: [
+        { id: '1', title: 'First post', createdAt: '2024-01-01' },
+        { id: '2', title: 'Second post', createdAt: '2024-01-02' },
+        { id: '3', title: 'Third post', createdAt: '2024-01-03' },
+      ],
+      hasMore: true,
+      cursor: 'page2',
+    },
+    page2: {
+      items: [
+        { id: '4', title: 'Fourth post', createdAt: '2024-01-04' },
+        { id: '5', title: 'Fifth post', createdAt: '2024-01-05' },
+      ],
+      hasMore: true,
+      cursor: 'page3',
+    },
+    page3: {
+      items: [
+        { id: '6', title: 'Sixth post', createdAt: '2024-01-06' },
+      ],
+      hasMore: false,
+      cursor: 'end',
+    },
+  };
+
+  const key = cursor ?? 'initial';
+  return pages[key]!;
+}
+
+// --- Basic usage ---
+
+const feed = new Feed<Post>();
+
+// Subscribe to feed state changes
+feed.subscribe(() => {
+  console.log(`Feed: ${feed.count} items, hasMore=${feed.hasMore}, cursor=${feed.cursor}`);
+});
+
+// Initial state
+console.log('Cursor:', feed.cursor);   // null
+console.log('Has more:', feed.hasMore); // true
+console.log('Items:', feed.count);      // 0
+
+// --- Load first page ---
+
+const page1 = fakeFetchPosts(feed.cursor);
+feed.appendPage(page1);
+
+console.log('After page 1:', feed.count);   // 3
+console.log('Cursor:', feed.cursor);         // 'page2'
+console.log('Has more:', feed.hasMore);      // true
+
+// --- Load next page (items accumulate) ---
+
+const page2 = fakeFetchPosts(feed.cursor);
+feed.appendPage(page2);
+
+console.log('After page 2:', feed.count);   // 5
+console.log('Cursor:', feed.cursor);         // 'page3'
+
+// --- Load final page ---
+
+const page3 = fakeFetchPosts(feed.cursor);
+feed.appendPage(page3);
+
+console.log('After page 3:', feed.count);   // 6
+console.log('Has more:', feed.hasMore);      // false (no more pages)
+
+// Access all accumulated items
+console.log('All items:', feed.items.map(p => p.title));
+
+// --- Prepend (for chat UIs / newest-first feeds) ---
+
+const chatFeed = new Feed<Post>();
+
+chatFeed.appendPage({
+  items: [
+    { id: 'c1', title: 'Latest message', createdAt: '2024-01-10' },
+    { id: 'c2', title: 'Previous message', createdAt: '2024-01-09' },
+  ],
+  hasMore: true,
+  cursor: 'older',
+});
+
+// Prepend older messages at the top (e.g., scrolling up in a chat)
+chatFeed.prependPage({
+  items: [
+    { id: 'c3', title: 'Oldest message', createdAt: '2024-01-08' },
+  ],
+  hasMore: false,
+  cursor: 'start',
+});
+
+console.log('Chat order:', chatFeed.items.map(p => p.title));
+// ['Oldest message', 'Latest message', 'Previous message']
+
+// --- Push items without affecting cursor ---
+
+feed.push({ id: '7', title: 'Optimistic post', createdAt: '2024-01-07' });
+console.log('After push:', feed.count); // 7
+
+// --- Filter items ---
+
+feed.filter(p => p.id !== '7'); // remove the optimistic post
+console.log('After filter:', feed.count); // 6
+
+// --- Pull-to-refresh (replacePage) ---
+
+feed.replacePage({
+  items: [
+    { id: 'r1', title: 'Refreshed post 1', createdAt: '2024-02-01' },
+    { id: 'r2', title: 'Refreshed post 2', createdAt: '2024-02-02' },
+  ],
+  hasMore: true,
+  cursor: 'refreshed-page2',
+});
+console.log('After replacePage:', feed.count); // 2 (replaced all)
+
+// --- setResult (update cursor/hasMore only) ---
+
+feed.setResult({ hasMore: false, cursor: 'final' });
+console.log('After setResult hasMore:', feed.hasMore); // false
+console.log('Items unchanged:', feed.count);           // 2
+
+// --- Reset ---
+
+feed.reset();
+console.log('After reset:', feed.count, feed.cursor, feed.hasMore); // 0, null, true

package/examples/primitive/model.ts

@@ -0,0 +1,82 @@
+import { Model } from 'mvc-kit';
+
+// Model: Reactive entity with validation and dirty tracking
+
+interface UserFormState {
+  name: string;
+  email: string;
+  age: number;
+}
+
+class UserFormModel extends Model<UserFormState> {
+  setName(name: string) {
+    this.set({ name });
+  }
+
+  setEmail(email: string) {
+    this.set({ email });
+  }
+
+  setAge(age: number) {
+    this.set({ age });
+  }
+
+  // Override to provide validation logic
+  protected validate(state: UserFormState) {
+    const errors: Partial<Record<keyof UserFormState, string>> = {};
+
+    if (!state.name.trim()) {
+      errors.name = 'Name is required';
+    }
+
+    if (!state.email.includes('@')) {
+      errors.email = 'Invalid email address';
+    }
+
+    if (state.age < 0 || state.age > 150) {
+      errors.age = 'Age must be between 0 and 150';
+    }
+
+    return errors;
+  }
+}
+
+// --- Usage ---
+
+const form = new UserFormModel({ name: '', email: '', age: 0 });
+
+// Subscribe to state changes
+form.subscribe((state) => {
+  console.log('Form state:', state);
+});
+
+// Check validation
+console.log('Initial valid:', form.valid); // false
+console.log('Initial errors:', form.errors); // { name: 'Name is required', email: 'Invalid email...' }
+
+// Update fields
+form.setName('John Doe');
+form.setEmail('john@example.com');
+form.setAge(30);
+
+console.log('After updates valid:', form.valid); // true
+console.log('After updates errors:', form.errors); // {}
+
+// Dirty tracking - check if state differs from committed baseline
+console.log('Is dirty:', form.dirty); // true (differs from initial state)
+
+// Commit - mark current state as the new baseline
+form.commit();
+console.log('After commit dirty:', form.dirty); // false
+
+// Make more changes
+form.setName('Jane Doe');
+console.log('After change dirty:', form.dirty); // true
+
+// Rollback - revert to committed state
+form.rollback();
+console.log('After rollback name:', form.state.name); // 'John Doe'
+console.log('After rollback dirty:', form.dirty); // false
+
+// Cleanup
+form.dispose();

package/examples/primitive/pagination.ts

@@ -0,0 +1,91 @@
+import { Pagination } from 'mvc-kit';
+
+// Pagination: Page-based state with array slicing pipeline
+//
+// A subscribable helper that manages page/pageSize state and slices
+// arrays accordingly. Designed to be a property on a ViewModel —
+// auto-tracked so ViewModel getters that read pagination state
+// recompute automatically.
+
+// --- Sample data ---
+
+const allItems = Array.from({ length: 47 }, (_, i) => ({
+  id: String(i + 1),
+  title: `Item ${i + 1}`,
+}));
+
+// --- Basic usage ---
+
+const pagination = new Pagination(); // default pageSize: 10
+
+// Subscribe to page changes
+pagination.subscribe(() => {
+  console.log(`Page ${pagination.page} of ${pagination.pageCount(allItems.length)}`);
+});
+
+// Read current state
+console.log('Page:', pagination.page);       // 1
+console.log('Page size:', pagination.pageSize); // 10
+
+// --- Apply slice pipeline ---
+
+const page1 = pagination.apply(allItems);
+console.log('Page 1 items:', page1.length); // 10
+console.log('First:', page1[0].title);      // 'Item 1'
+console.log('Last:', page1[9].title);       // 'Item 10'
+
+// --- Navigation ---
+
+pagination.nextPage();
+const page2 = pagination.apply(allItems);
+console.log('Page 2 first:', page2[0].title); // 'Item 11'
+
+pagination.nextPage();
+pagination.nextPage();
+pagination.nextPage(); // page 5 (last page)
+
+const lastPage = pagination.apply(allItems);
+console.log('Last page items:', lastPage.length); // 7 (47 - 40)
+console.log('Last page first:', lastPage[0].title); // 'Item 41'
+
+// --- Boundary checks ---
+
+console.log('Page count:', pagination.pageCount(allItems.length)); // 5
+console.log('Has next:', pagination.hasNext(allItems.length));     // false (on last page)
+console.log('Has prev:', pagination.hasPrev());                    // true
+
+pagination.prevPage();
+console.log('After prevPage:', pagination.page); // 4
+
+// prevPage on page 1 is a no-op
+pagination.setPage(1);
+pagination.prevPage();
+console.log('After prevPage on page 1:', pagination.page); // 1
+
+// --- Change page size ---
+
+pagination.setPageSize(20); // resets to page 1 automatically
+console.log('New page size:', pagination.pageSize);                 // 20
+console.log('Page after resize:', pagination.page);                 // 1
+console.log('New page count:', pagination.pageCount(allItems.length)); // 3
+
+const bigPage = pagination.apply(allItems);
+console.log('Items on resized page:', bigPage.length); // 20
+
+// --- Navigate to specific page ---
+
+pagination.setPage(3);
+const thirdPage = pagination.apply(allItems);
+console.log('Page 3 items:', thirdPage.length); // 7 (47 - 40)
+
+// --- Custom initial page size ---
+
+const smallPages = new Pagination({ pageSize: 5 });
+console.log('Custom page size:', smallPages.pageSize);                    // 5
+console.log('Custom page count:', smallPages.pageCount(allItems.length)); // 10
+
+// --- Reset ---
+
+pagination.setPage(3);
+pagination.reset(); // resets to page 1
+console.log('After reset page:', pagination.page); // 1