mvc-kit 2.12.0 → 2.12.2

package/src/Sorting.test.ts

@@ -0,0 +1,334 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Sorting } from './Sorting';
+import type { SortDescriptor } from './Sorting';
+import { ViewModel } from './ViewModel';
+
+// ============================================================================
+// Sorting unit tests
+// ============================================================================
+
+describe('Sorting', () => {
+  describe('construction', () => {
+    it('defaults to empty sorts', () => {
+      const s = new Sorting();
+      expect(s.sorts).toEqual([]);
+      expect(s.key).toBe(null);
+      expect(s.direction).toBe('asc');
+    });
+
+    it('accepts initial sorts', () => {
+      const s = new Sorting({ sorts: [{ key: 'name', direction: 'asc' }] });
+      expect(s.sorts).toEqual([{ key: 'name', direction: 'asc' }]);
+      expect(s.key).toBe('name');
+      expect(s.direction).toBe('asc');
+    });
+
+    it('defensively copies initial sorts', () => {
+      const initial: SortDescriptor[] = [{ key: 'name', direction: 'asc' }];
+      const s = new Sorting({ sorts: initial });
+      initial[0].key = 'mutated';
+      expect(s.sorts[0].key).toBe('name');
+    });
+  });
+
+  describe('3-click toggle cycle', () => {
+    it('cycles: not sorted → asc → desc → removed', () => {
+      const s = new Sorting();
+      const listener = vi.fn();
+      s.subscribe(listener);
+
+      // Not sorted → asc
+      s.toggle('name');
+      expect(s.sorts).toEqual([{ key: 'name', direction: 'asc' }]);
+      expect(listener).toHaveBeenCalledTimes(1);
+
+      // asc → desc
+      s.toggle('name');
+      expect(s.sorts).toEqual([{ key: 'name', direction: 'desc' }]);
+      expect(listener).toHaveBeenCalledTimes(2);
+
+      // desc → removed
+      s.toggle('name');
+      expect(s.sorts).toEqual([]);
+      expect(listener).toHaveBeenCalledTimes(3);
+    });
+  });
+
+  describe('multi-column sorting', () => {
+    it('adds columns independently', () => {
+      const s = new Sorting();
+      s.toggle('dept');
+      s.toggle('name');
+      expect(s.sorts).toEqual([
+        { key: 'dept', direction: 'asc' },
+        { key: 'name', direction: 'asc' },
+      ]);
+    });
+
+    it('flips second column without affecting first', () => {
+      const s = new Sorting();
+      s.toggle('dept');
+      s.toggle('name');
+      s.toggle('name'); // flip name to desc
+      expect(s.sorts).toEqual([
+        { key: 'dept', direction: 'asc' },
+        { key: 'name', direction: 'desc' },
+      ]);
+    });
+
+    it('removes second column, keeping first', () => {
+      const s = new Sorting();
+      s.toggle('dept');
+      s.toggle('name');
+      s.toggle('name'); // desc
+      s.toggle('name'); // remove
+      expect(s.sorts).toEqual([{ key: 'dept', direction: 'asc' }]);
+    });
+  });
+
+  describe('query methods', () => {
+    it('isSorted returns correct values', () => {
+      const s = new Sorting({ sorts: [{ key: 'name', direction: 'asc' }] });
+      expect(s.isSorted('name')).toBe(true);
+      expect(s.isSorted('age')).toBe(false);
+    });
+
+    it('directionOf returns direction or null', () => {
+      const s = new Sorting({ sorts: [{ key: 'name', direction: 'desc' }] });
+      expect(s.directionOf('name')).toBe('desc');
+      expect(s.directionOf('age')).toBe(null);
+    });
+
+    it('indexOf returns index or -1', () => {
+      const s = new Sorting({
+        sorts: [
+          { key: 'dept', direction: 'asc' },
+          { key: 'name', direction: 'desc' },
+        ],
+      });
+      expect(s.indexOf('dept')).toBe(0);
+      expect(s.indexOf('name')).toBe(1);
+      expect(s.indexOf('age')).toBe(-1);
+    });
+  });
+
+  describe('setSort / setSorts / reset', () => {
+    it('setSort replaces all with single sort', () => {
+      const s = new Sorting({
+        sorts: [
+          { key: 'dept', direction: 'asc' },
+          { key: 'name', direction: 'desc' },
+        ],
+      });
+      s.setSort('age', 'asc');
+      expect(s.sorts).toEqual([{ key: 'age', direction: 'asc' }]);
+    });
+
+    it('setSorts replaces all', () => {
+      const s = new Sorting();
+      s.setSorts([
+        { key: 'a', direction: 'asc' },
+        { key: 'b', direction: 'desc' },
+      ]);
+      expect(s.sorts).toEqual([
+        { key: 'a', direction: 'asc' },
+        { key: 'b', direction: 'desc' },
+      ]);
+    });
+
+    it('reset clears all sorts', () => {
+      const s = new Sorting({ sorts: [{ key: 'name', direction: 'asc' }] });
+      s.reset();
+      expect(s.sorts).toEqual([]);
+    });
+  });
+
+  describe('apply', () => {
+    const items = [
+      { name: 'Charlie', age: 30 },
+      { name: 'Alice', age: 25 },
+      { name: 'Bob', age: 30 },
+    ];
+
+    it('returns items unchanged when no sorts', () => {
+      const s = new Sorting();
+      expect(s.apply(items)).toEqual(items);
+    });
+
+    it('sorts strings ascending by default', () => {
+      const s = new Sorting({ sorts: [{ key: 'name', direction: 'asc' }] });
+      const result = s.apply(items);
+      expect(result.map(i => i.name)).toEqual(['Alice', 'Bob', 'Charlie']);
+    });
+
+    it('sorts strings descending', () => {
+      const s = new Sorting({ sorts: [{ key: 'name', direction: 'desc' }] });
+      const result = s.apply(items);
+      expect(result.map(i => i.name)).toEqual(['Charlie', 'Bob', 'Alice']);
+    });
+
+    it('sorts numbers', () => {
+      const s = new Sorting({ sorts: [{ key: 'age', direction: 'asc' }] });
+      const result = s.apply(items);
+      expect(result.map(i => i.age)).toEqual([25, 30, 30]);
+    });
+
+    it('applies multi-column sort (primary then secondary)', () => {
+      const s = new Sorting({
+        sorts: [
+          { key: 'age', direction: 'desc' },
+          { key: 'name', direction: 'asc' },
+        ],
+      });
+      const result = s.apply(items);
+      // age desc first, then name asc within same age
+      expect(result.map(i => i.name)).toEqual(['Bob', 'Charlie', 'Alice']);
+    });
+
+    it('uses custom compareFn', () => {
+      const s = new Sorting({ sorts: [{ key: 'name', direction: 'asc' }] });
+      const reversed = (a: any, b: any, key: string) => {
+        return String(b[key]).localeCompare(String(a[key]));
+      };
+      const result = s.apply(items, reversed);
+      expect(result.map(i => i.name)).toEqual(['Charlie', 'Bob', 'Alice']);
+    });
+
+    it('does not mutate the original array', () => {
+      const s = new Sorting({ sorts: [{ key: 'name', direction: 'asc' }] });
+      const original = [...items];
+      s.apply(items);
+      expect(items).toEqual(original);
+    });
+
+    it('handles null values', () => {
+      const data = [
+        { name: 'Bob', value: 2 },
+        { name: 'Alice', value: null },
+        { name: 'Charlie', value: 1 },
+      ];
+      const s = new Sorting({ sorts: [{ key: 'value', direction: 'asc' }] });
+      const result = s.apply(data);
+      expect(result.map(i => i.name)).toEqual(['Alice', 'Charlie', 'Bob']);
+    });
+  });
+
+  describe('subscribe notifications', () => {
+    it('notifies on toggle', () => {
+      const s = new Sorting();
+      const listener = vi.fn();
+      s.subscribe(listener);
+      s.toggle('name');
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('notifies on setSort', () => {
+      const s = new Sorting();
+      const listener = vi.fn();
+      s.subscribe(listener);
+      s.setSort('name', 'asc');
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('notifies on setSorts', () => {
+      const s = new Sorting();
+      const listener = vi.fn();
+      s.subscribe(listener);
+      s.setSorts([{ key: 'name', direction: 'asc' }]);
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('notifies on reset', () => {
+      const s = new Sorting({ sorts: [{ key: 'name', direction: 'asc' }] });
+      const listener = vi.fn();
+      s.subscribe(listener);
+      s.reset();
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('unsubscribe stops notifications', () => {
+      const s = new Sorting();
+      const listener = vi.fn();
+      const unsub = s.subscribe(listener);
+      unsub();
+      s.toggle('name');
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('auto-tracking integration', () => {
+    it('ViewModel getter invalidates when sorting changes', () => {
+      let sortCallCount = 0;
+
+      class TestVM extends ViewModel {
+        readonly sorting = new Sorting<{ name: string }>();
+        private _items = [{ name: 'Charlie' }, { name: 'Alice' }, { name: 'Bob' }];
+
+        get sorted() {
+          sortCallCount++;
+          return this.sorting.apply(this._items);
+        }
+      }
+
+      const vm = new TestVM();
+      vm.init();
+
+      // First access: computes
+      expect(vm.sorted.map(i => i.name)).toEqual(['Charlie', 'Alice', 'Bob']);
+      expect(sortCallCount).toBe(1);
+
+      // Cached
+      vm.sorted;
+      expect(sortCallCount).toBe(1);
+
+      // Toggle sorting — getter should recompute
+      vm.sorting.toggle('name');
+      expect(vm.sorted.map(i => i.name)).toEqual(['Alice', 'Bob', 'Charlie']);
+      expect(sortCallCount).toBe(2);
+
+      // Cached again
+      vm.sorted;
+      expect(sortCallCount).toBe(2);
+
+      vm.dispose();
+    });
+
+    it('ViewModel subscribe fires when sorting changes', () => {
+      class TestVM extends ViewModel {
+        readonly sorting = new Sorting();
+      }
+
+      const vm = new TestVM();
+      vm.init();
+
+      const listener = vi.fn();
+      vm.subscribe(listener);
+
+      vm.sorting.toggle('name');
+      expect(listener).toHaveBeenCalledTimes(1);
+
+      vm.dispose();
+    });
+  });
+
+  describe('method binding', () => {
+    it('destructured methods work point-free', () => {
+      const sorting = new Sorting();
+      const { toggle, reset, setSort } = sorting;
+      toggle('name');
+      expect(sorting.sorts).toHaveLength(1);
+      expect(sorting.sorts[0].key).toBe('name');
+      reset();
+      expect(sorting.sorts).toHaveLength(0);
+      setSort('age', 'desc');
+      expect(sorting.sorts[0].direction).toBe('desc');
+    });
+
+    it('methods work as React-style callbacks', () => {
+      const sorting = new Sorting();
+      const callback: (key: string) => void = sorting.toggle;
+      callback('name');
+      expect(sorting.sorts[0].key).toBe('name');
+    });
+  });
+});

package/src/Sorting.ts

@@ -0,0 +1,135 @@
+import { Trackable } from './Trackable';
+
+/** Describes a single sort column with key and direction. */
+export interface SortDescriptor {
+  key: string;
+  direction: 'asc' | 'desc';
+}
+
+/**
+ * Multi-column sort state manager with a comparator pipeline.
+ * Maintains an ordered list of sort descriptors and applies them to arrays.
+ * Subscribable — auto-tracked when used as a ViewModel property.
+ */
+export class Sorting<T = any> extends Trackable {
+  private _sorts: readonly SortDescriptor[];
+
+  constructor(options?: { sorts?: SortDescriptor[] }) {
+    super();
+    this._sorts = Object.freeze(options?.sorts?.map(s => ({ ...s })) ?? []);
+  }
+
+  // ── Readable state ──
+
+  /** Current list of active sort descriptors, in priority order. */
+  get sorts(): readonly SortDescriptor[] {
+    return this._sorts;
+  }
+
+  /** Primary sort key (first descriptor), or null when empty. */
+  get key(): string | null {
+    return this._sorts.length > 0 ? this._sorts[0].key : null;
+  }
+
+  /** Primary sort direction. Defaults to 'asc' when empty. */
+  get direction(): 'asc' | 'desc' {
+    return this._sorts.length > 0 ? this._sorts[0].direction : 'asc';
+  }
+
+  // ── Query ──
+
+  /** Whether the given key is currently sorted. */
+  isSorted(key: string): boolean {
+    return this._sorts.some(s => s.key === key);
+  }
+
+  /** Returns the sort direction for a key, or null if not sorted. */
+  directionOf(key: string): 'asc' | 'desc' | null {
+    const found = this._sorts.find(s => s.key === key);
+    return found ? found.direction : null;
+  }
+
+  /** Returns the priority index of a sorted key, or -1 if not sorted. */
+  indexOf(key: string): number {
+    return this._sorts.findIndex(s => s.key === key);
+  }
+
+  // ── Actions ──
+
+  /** 3-click cycle: not sorted → asc → desc → removed. */
+  toggle(key: string): void {
+    const idx = this.indexOf(key);
+    if (idx === -1) {
+      // Add as asc
+      this._sorts = Object.freeze([...this._sorts, { key, direction: 'asc' as const }]);
+    } else if (this._sorts[idx].direction === 'asc') {
+      // Flip to desc
+      const next = this._sorts.map((s, i) =>
+        i === idx ? { key: s.key, direction: 'desc' as const } : s
+      );
+      this._sorts = Object.freeze(next);
+    } else {
+      // Remove
+      this._sorts = Object.freeze(this._sorts.filter((_, i) => i !== idx));
+    }
+    this.notify();
+  }
+
+  /** Replace all with a single sort. */
+  setSort(key: string, direction: 'asc' | 'desc'): void {
+    this._sorts = Object.freeze([{ key, direction }]);
+    this.notify();
+  }
+
+  /** Replace all sorts. */
+  setSorts(sorts: SortDescriptor[]): void {
+    this._sorts = Object.freeze(sorts.map(s => ({ ...s })));
+    this.notify();
+  }
+
+  /** Clear all sort descriptors. */
+  reset(): void {
+    this._sorts = Object.freeze([]);
+    this.notify();
+  }
+
+  // ── Pipeline ──
+
+  /** Sort an array using the current descriptors. Returns a new sorted array. */
+  apply(
+    items: T[],
+    compareFn?: (a: T, b: T, key: string, dir: 'asc' | 'desc') => number,
+  ): T[] {
+    if (this._sorts.length === 0) return items;
+    const sorted = items.slice();
+    const sorts = this._sorts;
+    sorted.sort((a, b) => {
+      for (const { key, direction } of sorts) {
+        let cmp: number;
+        if (compareFn) {
+          cmp = compareFn(a, b, key, direction);
+        } else {
+          cmp = defaultCompare(a, b, key);
+        }
+        if (direction === 'desc') cmp = -cmp;
+        if (cmp !== 0) return cmp;
+      }
+      return 0;
+    });
+    return sorted;
+  }
+}
+
+function defaultCompare(a: any, b: any, key: string): number {
+  const aVal = a[key];
+  const bVal = b[key];
+  if (aVal == null && bVal == null) return 0;
+  if (aVal == null) return -1;
+  if (bVal == null) return 1;
+  if (typeof aVal === 'string' && typeof bVal === 'string') {
+    return aVal.localeCompare(bVal);
+  }
+  if (aVal < bVal) return -1;
+  if (aVal > bVal) return 1;
+  return 0;
+}

package/src/Trackable.md

@@ -0,0 +1,166 @@
+# Trackable
+
+Base class for custom reactive objects that integrate with ViewModel's auto-tracking system. Provides subscribable notifications, disposal lifecycle, cleanup infrastructure, and automatic method binding.
+
+## When to Use
+
+Use `Trackable` when building custom classes that need to:
+- **Integrate with ViewModel getters** — any `Trackable` property on a ViewModel is auto-tracked; getter results invalidate when you call `notify()`
+- **Work with `useLocal`** — Trackable objects get automatic React re-renders via version-counter subscription
+- **Manage cleanup** — `addCleanup()` + `disposeSignal` for event listeners, timers, and external subscriptions
+- **Support point-free callbacks** — public methods are auto-bound in the constructor
+
+Common use cases: RPC query wrappers, Firebase/Supabase real-time subscriptions, WebSocket message handlers, tRPC query objects, or any third-party SDK integration that manages its own async state.
+
+## When NOT to Use
+
+- **Need state + getters + async tracking** → Use `ViewModel`
+- **Need a shared data cache** → Use `Collection` or `Resource`
+- **Need validation + dirty tracking** → Use `Model`
+- **Need stateless orchestration** → Use `Controller`
+
+## API
+
+### Constructor
+
+```ts
+class MyTrackable extends Trackable {
+  constructor() {
+    super(); // auto-binds all public methods
+  }
+}
+```
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `disposed` | `boolean` | Whether `dispose()` has been called |
+| `disposeSignal` | `AbortSignal` | Fires when disposed; lazily created |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `subscribe(cb)` | Subscribe to change notifications. Returns unsubscribe function |
+| `dispose()` | Tear down: abort signal, run cleanups, clear listeners, call `onDispose()`. Idempotent |
+
+### Protected Methods
+
+| Method | Description |
+|--------|-------------|
+| `notify()` | Notify all subscribers that state changed |
+| `addCleanup(fn)` | Register a function to run on `dispose()` |
+| `onDispose()` | Lifecycle hook called at end of `dispose()`. Override for custom teardown |
+
+## Example: RPC Query Integration
+
+```ts
+import { Trackable } from 'mvc-kit';
+
+class RPCQuery<Args, Data> extends Trackable {
+  private _data: Data | undefined;
+  private _loading = false;
+  private _callCounter = 0;
+
+  get data() { return this._data; }
+  get loading() { return this._loading; }
+
+  constructor(private endpoint: string) {
+    super();
+  }
+
+  async call(args?: Args): Promise<Data> {
+    const callId = ++this._callCounter;
+    this._loading = true;
+    this.notify();
+
+    try {
+      const result = await rpcClient.call<Data>(this.endpoint, args);
+      if (callId === this._callCounter) {
+        this._data = result;
+        this._loading = false;
+        this.notify();
+      }
+      return result;
+    } catch (err) {
+      if (callId === this._callCounter) {
+        this._loading = false;
+        this.notify();
+      }
+      throw err;
+    }
+  }
+}
+```
+
+## ViewModel Integration (Auto-Tracking)
+
+```ts
+class UsersVM extends ViewModel<{ search: string }> {
+  readonly users = new RPCQuery<void, User[]>('Users.List');
+
+  // Auto-tracked — recomputes when users.notify() fires
+  get userList() {
+    return this.users.data ?? [];
+  }
+
+  get isLoading() {
+    return this.users.loading;
+  }
+
+  async onInit() {
+    await this.users.call();
+  }
+}
+```
+
+## React Usage (useLocal)
+
+Trackable objects work with `useLocal` — the component re-renders when `notify()` fires:
+
+```tsx
+function UserSearch() {
+  const query = useLocal(() => new RPCQuery<string, User[]>('Users.Search'));
+
+  return (
+    <div>
+      {query.loading && <Spinner />}
+      {query.data?.map(user => <UserCard key={user.id} user={user} />)}
+      <button onClick={() => query.call('alice')}>Search</button>
+    </div>
+  );
+}
+```
+
+## Cleanup with addCleanup
+
+```ts
+class LiveQuery extends Trackable {
+  constructor(private channel: string) {
+    super();
+    const unsub = eventSource.on(channel, () => this.refresh());
+    this.addCleanup(unsub); // runs automatically on dispose
+
+    // Or use disposeSignal for fetch abort
+    this.loadInitial();
+  }
+
+  private async loadInitial() {
+    await fetch('/api/data', { signal: this.disposeSignal });
+  }
+}
+```
+
+## Method Binding
+
+All public methods are auto-bound — safe to pass as callbacks:
+
+```tsx
+const { call, dispose } = query;
+<button onClick={call}>Fetch</button>  // works without wrapper
+```
+
+## Internal Usage
+
+`Trackable` is the base class for mvc-kit's composable helpers: `Sorting`, `Selection`, `Feed`, `Pagination`, and `Pending` all extend it.