mvc-kit 2.12.0 → 2.12.2

package/src/Model.ts

@@ -0,0 +1,260 @@
+import type { Listener, Updater, Subscribable, ValidationErrors, EventPayload } from './types';
+import { bindPublicMethods } from './bindPublicMethods';
+import { resolveDraftUpdater } from './produceDraft';
+
+const __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;
+const PROTECTED_KEYS = new Set(['set', 'validate', 'addCleanup', 'subscribeTo', 'listenTo']);
+
+function freeze<T>(obj: T): T {
+  return __DEV__ ? Object.freeze(obj) as T : obj;
+}
+
+/**
+ * Reactive entity with validation and dirty tracking.
+ */
+export abstract class Model<S extends object> implements Subscribable<S> {
+  private _state: Readonly<S>;
+  private _committed: Readonly<S>;
+  private _disposed = false;
+  private _initialized = false;
+  private _listeners = new Set<Listener<S>>();
+  private _abortController: AbortController | null = null;
+  private _cleanups: (() => void)[] | null = null;
+  private _cachedDirty: boolean | null = null;
+  private _cachedErrors: ValidationErrors<S> | null = null;
+
+  constructor(initialState: S) {
+    const frozen = freeze({ ...initialState });
+    this._state = frozen;
+    this._committed = frozen;
+    bindPublicMethods(this, Object.prototype, PROTECTED_KEYS);
+  }
+
+  /** Current frozen state object. */
+  get state(): S {
+    return this._state;
+  }
+
+  /**
+   * The baseline state for dirty tracking.
+   */
+  get committed(): S {
+    return this._committed;
+  }
+
+  /**
+   * True if current state differs from committed state.
+   */
+  get dirty(): boolean {
+    if (this._cachedDirty === null) {
+      this._cachedDirty = !this._shallowEqual(this._state, this._committed);
+    }
+    return this._cachedDirty;
+  }
+
+  /**
+   * Validation errors for the current state.
+   */
+  get errors(): ValidationErrors<S> {
+    if (this._cachedErrors === null) {
+      this._cachedErrors = this.validate(this._state);
+    }
+    return this._cachedErrors;
+  }
+
+  /**
+   * True if there are no validation errors.
+   */
+  get valid(): boolean {
+    return Object.keys(this.errors).length === 0;
+  }
+
+  /** Whether this instance has been disposed. */
+  get disposed(): boolean {
+    return this._disposed;
+  }
+
+  /** Whether init() has been called. */
+  get initialized(): boolean {
+    return this._initialized;
+  }
+
+  /** AbortSignal that fires when this instance is disposed. Lazily created. */
+  get disposeSignal(): AbortSignal {
+    if (!this._abortController) {
+      this._abortController = new AbortController();
+    }
+    return this._abortController.signal;
+  }
+
+  /** Initializes the instance. Called automatically by React hooks after mount. */
+  init(): void | Promise<void> {
+    if (this._initialized || this._disposed) return;
+    this._initialized = true;
+    return this.onInit?.();
+  }
+
+  /**
+   * Merges partial state with validation. No-op if no values changed by reference.
+   * @protected
+   */
+  protected set(partialOrUpdater: Partial<S> | Updater<S> | ((draft: S) => void)): void {
+    if (this._disposed) {
+      throw new Error('Cannot set state on disposed Model');
+    }
+
+    let partial: Partial<S>;
+    if (typeof partialOrUpdater === 'function') {
+      const result = resolveDraftUpdater<S>(this._state, partialOrUpdater as (s: S) => Partial<S> | void);
+      if (!result) return;
+      partial = result;
+    } else {
+      partial = partialOrUpdater;
+    }
+
+    // Check if any values actually changed (shallow equality)
+    const keys = Object.keys(partial) as (keyof S)[];
+    const hasChanges = keys.some(
+      (key) => partial[key] !== this._state[key]
+    );
+
+    if (!hasChanges) {
+      return;
+    }
+
+    const prev = this._state;
+    const next = freeze({ ...prev, ...partial });
+    this._state = next;
+    this._cachedDirty = null;
+    this._cachedErrors = null;
+
+    this.onSet?.(prev, next);
+
+    for (const listener of this._listeners) {
+      listener(next, prev);
+    }
+  }
+
+  /**
+   * Mark current state as the new baseline (not dirty).
+   */
+  commit(): void {
+    if (this._disposed) {
+      throw new Error('Cannot commit on disposed Model');
+    }
+    this._committed = this._state;
+    this._cachedDirty = null;
+    this._cachedErrors = null;
+  }
+
+  /**
+   * Revert state to committed baseline.
+   */
+  rollback(): void {
+    if (this._disposed) {
+      throw new Error('Cannot rollback on disposed Model');
+    }
+
+    if (this._shallowEqual(this._state, this._committed)) {
+      return;
+    }
+
+    const prev = this._state;
+    this._state = this._committed;
+    this._cachedDirty = null;
+    this._cachedErrors = null;
+
+    this.onSet?.(prev, this._state);
+
+    for (const listener of this._listeners) {
+      listener(this._state, prev);
+    }
+  }
+
+  /** Subscribes to state changes. Returns an unsubscribe function. */
+  subscribe(listener: Listener<S>): () => void {
+    if (this._disposed) {
+      return () => {};
+    }
+
+    this._listeners.add(listener);
+
+    return () => {
+      this._listeners.delete(listener);
+    };
+  }
+
+  /** Tears down the instance, releasing all subscriptions and resources. */
+  dispose(): void {
+    if (this._disposed) {
+      return;
+    }
+
+    this._disposed = true;
+    this._abortController?.abort();
+    if (this._cleanups) {
+      for (const fn of this._cleanups) fn();
+      this._cleanups = null;
+    }
+    this.onDispose?.();
+    this._listeners.clear();
+  }
+
+  /**
+   * Override to provide validation logic.
+   * Return an object mapping field keys to error messages.
+   */
+  protected validate(_state: S): ValidationErrors<S> {
+    return {};
+  }
+
+  /** Registers a cleanup function to be called on dispose. @protected */
+  protected addCleanup(fn: () => void): void {
+    if (!this._cleanups) {
+      this._cleanups = [];
+    }
+    this._cleanups.push(fn);
+  }
+
+  /** Subscribes to an external Subscribable with automatic cleanup on dispose. @protected */
+  protected subscribeTo<T>(source: Subscribable<T>, listener: Listener<T>): () => void {
+    const unsubscribe = source.subscribe(listener);
+    this.addCleanup(unsubscribe);
+    return unsubscribe;
+  }
+
+  /** Subscribes to a typed event on a Channel or EventBus with automatic cleanup on dispose. @protected */
+  protected listenTo<K extends string, S extends { on(event: K, handler: (payload: any) => void): () => void }>(
+    source: S,
+    event: K,
+    handler: (payload: EventPayload<S, K>) => void,
+  ): () => void {
+    const unsubscribe = source.on(event, handler);
+    this.addCleanup(unsubscribe);
+    return unsubscribe;
+  }
+
+  /** Lifecycle hook called after every set() with the previous state. @protected */
+  protected onSet?(prev: S, next: S): void;
+  /** Lifecycle hook called at the end of init(). Override to load initial data. @protected */
+  protected onInit?(): void | Promise<void>;
+  /** Lifecycle hook called during dispose(). Override for custom teardown. @protected */
+  protected onDispose?(): void;
+
+  private _shallowEqual(a: S, b: S): boolean {
+    const keysA = Object.keys(a) as (keyof S)[];
+    const keysB = Object.keys(b) as (keyof S)[];
+
+    if (keysA.length !== keysB.length) {
+      return false;
+    }
+
+    for (const key of keysA) {
+      if (a[key] !== b[key]) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+}

package/src/Pagination.md

@@ -0,0 +1,168 @@
+# Pagination
+
+Page-based pagination helper. Manages page number and page size, slices arrays for the current page. Extends [`Trackable`](./Trackable.md) — subscribable, disposable, and auto-bound.
+
+---
+
+## When to Use
+
+Use Pagination as a ViewModel property for client-side paginated tables and lists. Auto-tracking ensures ViewModel getters that read from Pagination auto-invalidate when page/pageSize changes.
+
+For server-side cursor-based pagination (infinite scroll), use `Feed` instead.
+
+---
+
+## Creating a Pagination Instance
+
+```typescript
+import { Pagination } from 'mvc-kit';
+
+// Default: pageSize 10
+readonly pagination = new Pagination();
+
+// Custom pageSize
+readonly pagination = new Pagination({ pageSize: 25 });
+```
+
+---
+
+## API
+
+### Readable State
+
+#### `page: number`
+
+Current page number (1-indexed).
+
+#### `pageSize: number`
+
+Number of items per page.
+
+### Derived Methods (Require Total)
+
+#### `pageCount(total: number): number`
+
+Total number of pages. Minimum 1.
+
+#### `hasNext(total: number): boolean`
+
+Whether there's a next page given the total item count.
+
+#### `hasPrev(): boolean`
+
+Whether there's a previous page (`page > 1`).
+
+### Actions
+
+#### `setPage(page: number): void`
+
+Set the current page. Clamped to minimum 1. No-op if already on that page.
+
+#### `setPageSize(size: number): void`
+
+Set page size and reset to page 1. Ignored if size < 1.
+
+#### `nextPage(): void`
+
+Advance to next page.
+
+#### `prevPage(): void`
+
+Go to previous page. No-op if already on page 1.
+
+#### `reset(): void`
+
+Reset to page 1. No-op if already on page 1.
+
+### Pipeline
+
+#### `apply<T>(items: T[]): T[]`
+
+Slice the array for the current page. Returns an empty array if the page is beyond the data.
+
+### Subscribable Interface
+
+#### `subscribe(cb: () => void): () => void`
+
+Subscribe to state changes. Returns an unsubscribe function.
+
+---
+
+## ViewModel Integration
+
+```typescript
+class UsersVM extends ViewModel<FilterState> {
+  readonly pagination = new Pagination({ pageSize: 25 });
+  readonly sorting = new Sorting<User>();
+  private users = singleton(UsersResource);
+
+  get filtered(): User[] {
+    // ... filter logic using this.state ...
+    return this.users.items;
+  }
+
+  get items(): User[] {
+    return this.pagination.apply(this.sorting.apply(this.filtered));
+  }
+
+  get total() { return this.filtered.length; }
+
+  setSearch(search: string) {
+    this.set({ search });
+    this.pagination.reset(); // Back to page 1 on filter change
+  }
+}
+```
+
+---
+
+## React Usage
+
+Pass the Pagination helper directly to DataTable with `paginationTotal`:
+
+```tsx
+<DataTable
+  items={vm.items}
+  columns={columns}
+  pagination={vm.pagination}
+  paginationTotal={vm.total}
+  renderPagination={info => (
+    <div>
+      <button disabled={!info.hasPrev} onClick={info.goPrev}>Prev</button>
+      <span>Page {info.page} of {info.pageCount}</span>
+      <button disabled={!info.hasNext} onClick={info.goNext}>Next</button>
+    </div>
+  )}
+/>
+```
+
+Or use the object-literal form for custom usage:
+
+```tsx
+<DataTable
+  items={vm.items}
+  columns={columns}
+  pageSize={vm.pagination.pageSize}
+  pagination={{
+    page: vm.pagination.page,
+    total: vm.total,
+    onPageChange: p => vm.pagination.setPage(p),
+  }}
+  renderPagination={info => (
+    <div>
+      <button disabled={!info.hasPrev} onClick={info.goPrev}>Prev</button>
+      <span>Page {info.page} of {info.pageCount}</span>
+      <button disabled={!info.hasNext} onClick={info.goNext}>Next</button>
+    </div>
+  )}
+/>
+```
+
+## Method Binding
+
+All public methods are auto-bound in the constructor. You can pass them point-free as callbacks without losing `this` context:
+
+```tsx
+const { nextPage, prevPage } = pagination;
+<button onClick={nextPage}>Next</button> // point-free works
+```

package/src/Pagination.test.ts

@@ -0,0 +1,244 @@
+import { describe, it, expect, vi } from 'vitest';
+import { Pagination } from './Pagination';
+import { ViewModel } from './ViewModel';
+
+describe('Pagination', () => {
+  describe('construction', () => {
+    it('defaults to page 1, pageSize 10', () => {
+      const p = new Pagination();
+      expect(p.page).toBe(1);
+      expect(p.pageSize).toBe(10);
+    });
+
+    it('accepts custom pageSize', () => {
+      const p = new Pagination({ pageSize: 25 });
+      expect(p.pageSize).toBe(25);
+    });
+  });
+
+  describe('page navigation', () => {
+    it('setPage changes page', () => {
+      const p = new Pagination();
+      p.setPage(3);
+      expect(p.page).toBe(3);
+    });
+
+    it('setPage clamps to minimum 1', () => {
+      const p = new Pagination();
+      p.setPage(0);
+      expect(p.page).toBe(1);
+      p.setPage(-5);
+      expect(p.page).toBe(1);
+    });
+
+    it('setPage floors fractional values', () => {
+      const p = new Pagination();
+      p.setPage(2.7);
+      expect(p.page).toBe(2);
+    });
+
+    it('setPage does not notify if page unchanged', () => {
+      const p = new Pagination();
+      const listener = vi.fn();
+      p.subscribe(listener);
+      p.setPage(1); // already on page 1
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('nextPage increments', () => {
+      const p = new Pagination();
+      p.nextPage();
+      expect(p.page).toBe(2);
+      p.nextPage();
+      expect(p.page).toBe(3);
+    });
+
+    it('prevPage decrements', () => {
+      const p = new Pagination();
+      p.setPage(3);
+      p.prevPage();
+      expect(p.page).toBe(2);
+    });
+
+    it('prevPage does not go below 1', () => {
+      const p = new Pagination();
+      const listener = vi.fn();
+      p.subscribe(listener);
+      p.prevPage();
+      expect(p.page).toBe(1);
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('derived methods', () => {
+    it('pageCount computes correctly', () => {
+      const p = new Pagination({ pageSize: 10 });
+      expect(p.pageCount(0)).toBe(1);
+      expect(p.pageCount(10)).toBe(1);
+      expect(p.pageCount(11)).toBe(2);
+      expect(p.pageCount(100)).toBe(10);
+    });
+
+    it('hasNext checks against total', () => {
+      const p = new Pagination({ pageSize: 10 });
+      expect(p.hasNext(25)).toBe(true);
+      p.setPage(3);
+      expect(p.hasNext(25)).toBe(false);
+    });
+
+    it('hasPrev checks page > 1', () => {
+      const p = new Pagination();
+      expect(p.hasPrev()).toBe(false);
+      p.setPage(2);
+      expect(p.hasPrev()).toBe(true);
+    });
+  });
+
+  describe('setPageSize', () => {
+    it('changes pageSize and resets to page 1', () => {
+      const p = new Pagination({ pageSize: 10 });
+      p.setPage(5);
+      p.setPageSize(25);
+      expect(p.pageSize).toBe(25);
+      expect(p.page).toBe(1);
+    });
+
+    it('ignores size < 1', () => {
+      const p = new Pagination({ pageSize: 10 });
+      const listener = vi.fn();
+      p.subscribe(listener);
+      p.setPageSize(0);
+      expect(p.pageSize).toBe(10);
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('reset', () => {
+    it('resets to page 1', () => {
+      const p = new Pagination();
+      p.setPage(5);
+      p.reset();
+      expect(p.page).toBe(1);
+    });
+
+    it('does not notify if already on page 1', () => {
+      const p = new Pagination();
+      const listener = vi.fn();
+      p.subscribe(listener);
+      p.reset();
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('apply', () => {
+    const items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
+
+    it('slices for page 1', () => {
+      const p = new Pagination({ pageSize: 5 });
+      expect(p.apply(items)).toEqual([1, 2, 3, 4, 5]);
+    });
+
+    it('slices for page 2', () => {
+      const p = new Pagination({ pageSize: 5 });
+      p.setPage(2);
+      expect(p.apply(items)).toEqual([6, 7, 8, 9, 10]);
+    });
+
+    it('handles last partial page', () => {
+      const p = new Pagination({ pageSize: 5 });
+      p.setPage(3);
+      expect(p.apply(items)).toEqual([11, 12]);
+    });
+
+    it('returns empty array for page beyond total', () => {
+      const p = new Pagination({ pageSize: 5 });
+      p.setPage(10);
+      expect(p.apply(items)).toEqual([]);
+    });
+  });
+
+  describe('subscribe notifications', () => {
+    it('notifies on setPage', () => {
+      const p = new Pagination();
+      const listener = vi.fn();
+      p.subscribe(listener);
+      p.setPage(2);
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('notifies on setPageSize', () => {
+      const p = new Pagination();
+      const listener = vi.fn();
+      p.subscribe(listener);
+      p.setPageSize(25);
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('notifies on nextPage', () => {
+      const p = new Pagination();
+      const listener = vi.fn();
+      p.subscribe(listener);
+      p.nextPage();
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('unsubscribe stops notifications', () => {
+      const p = new Pagination();
+      const listener = vi.fn();
+      const unsub = p.subscribe(listener);
+      unsub();
+      p.setPage(2);
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('auto-tracking integration', () => {
+    it('ViewModel getter invalidates when pagination changes', () => {
+      let applyCallCount = 0;
+
+      class TestVM extends ViewModel {
+        readonly pagination = new Pagination({ pageSize: 2 });
+        private _items = [1, 2, 3, 4, 5, 6];
+
+        get items() {
+          applyCallCount++;
+          return this.pagination.apply(this._items);
+        }
+      }
+
+      const vm = new TestVM();
+      vm.init();
+
+      expect(vm.items).toEqual([1, 2]);
+      expect(applyCallCount).toBe(1);
+
+      // Cached
+      vm.items;
+      expect(applyCallCount).toBe(1);
+
+      // Change page — getter should recompute
+      vm.pagination.setPage(2);
+      expect(vm.items).toEqual([3, 4]);
+      expect(applyCallCount).toBe(2);
+
+      vm.dispose();
+    });
+  });
+
+  describe('method binding', () => {
+    it('destructured methods work point-free', () => {
+      const pagination = new Pagination({ pageSize: 5 });
+      const { nextPage, prevPage, setPage, reset } = pagination;
+      nextPage();
+      expect(pagination.page).toBe(2);
+      nextPage();
+      expect(pagination.page).toBe(3);
+      prevPage();
+      expect(pagination.page).toBe(2);
+      setPage(5);
+      expect(pagination.page).toBe(5);
+      reset();
+      expect(pagination.page).toBe(1);
+    });
+  });
+});