mvc-kit 2.12.0 → 2.12.2

package/src/produceDraft.test.ts

@@ -0,0 +1,394 @@
+import { describe, it, expect } from 'vitest';
+import { produceDraft, resolveDraftUpdater } from './produceDraft';
+
+describe('produceDraft', () => {
+  // ── Flat mutations ──────────────────────────────────────────────
+
+  it('applies a single flat property mutation', () => {
+    const state = { count: 0, name: 'test' };
+    const result = produceDraft(state, (d) => {
+      d.count = 5;
+    });
+    expect(result).toEqual({ count: 5 });
+  });
+
+  it('applies multiple flat property mutations', () => {
+    const state = { count: 0, name: 'test', active: false };
+    const result = produceDraft(state, (d) => {
+      d.count = 10;
+      d.name = 'updated';
+    });
+    expect(result).toEqual({ count: 10, name: 'updated' });
+  });
+
+  it('returns only changed keys, omitting unchanged ones', () => {
+    const state = { a: 1, b: 2, c: 3 };
+    const result = produceDraft(state, (d) => {
+      d.b = 20;
+    });
+    expect(result).toEqual({ b: 20 });
+    expect(result).not.toHaveProperty('a');
+    expect(result).not.toHaveProperty('c');
+  });
+
+  // ── No-op detection ─────────────────────────────────────────────
+
+  it('returns null for empty mutator', () => {
+    const state = { count: 0, name: 'test' };
+    const result = produceDraft(state, () => {});
+    expect(result).toBeNull();
+  });
+
+  it('returns null when assigning same value (flat)', () => {
+    const state = { count: 5, name: 'test' };
+    const result = produceDraft(state, (d) => {
+      d.count = 5;
+      d.name = 'test';
+    });
+    expect(result).toBeNull();
+  });
+
+  it('returns null when assigning same value (nested)', () => {
+    const state = { config: { theme: 'dark', size: 14 } };
+    const result = produceDraft(state, (d) => {
+      d.config.theme = 'dark';
+    });
+    expect(result).toBeNull();
+  });
+
+  // ── Nested mutations ────────────────────────────────────────────
+
+  it('applies single-level nested mutation', () => {
+    const state = { config: { theme: 'dark', size: 14 }, count: 0 };
+    const result = produceDraft(state, (d) => {
+      d.config.theme = 'light';
+    });
+    expect(result).toEqual({ config: { theme: 'light', size: 14 } });
+    expect(result).not.toHaveProperty('count');
+  });
+
+  it('preserves unchanged siblings in nested object (structural sharing)', () => {
+    const inner = { x: 10 };
+    const state = { a: { b: inner, c: { y: 20 } } };
+    const result = produceDraft(state, (d) => {
+      d.a.c.y = 30;
+    });
+
+    // Changed path gets new reference
+    expect(result!.a!.c).toEqual({ y: 30 });
+    expect(result!.a!.c).not.toBe(state.a.c);
+
+    // Unchanged sibling keeps same reference
+    expect((result!.a as any).b).toBe(inner);
+  });
+
+  it('handles deep nesting (3 levels)', () => {
+    const state = { a: { b: { c: { d: 1 } } } };
+    const result = produceDraft(state, (d) => {
+      d.a.b.c.d = 2;
+    });
+    expect(result).toEqual({ a: { b: { c: { d: 2 } } } });
+  });
+
+  it('handles multiple nested mutations in same object', () => {
+    const state = { config: { theme: 'dark', size: 14, lang: 'en' } };
+    const result = produceDraft(state, (d) => {
+      d.config.theme = 'light';
+      d.config.size = 16;
+    });
+    expect(result).toEqual({ config: { theme: 'light', size: 16, lang: 'en' } });
+  });
+
+  it('handles mutations in different nested objects', () => {
+    const state = { a: { x: 1 }, b: { y: 2 } };
+    const result = produceDraft(state, (d) => {
+      d.a.x = 10;
+      d.b.y = 20;
+    });
+    expect(result).toEqual({ a: { x: 10 }, b: { y: 20 } });
+  });
+
+  // ── Read-after-write ────────────────────────────────────────────
+
+  it('reads reflect prior writes (flat)', () => {
+    const state = { count: 0 };
+    const result = produceDraft(state, (d) => {
+      d.count = 5;
+      d.count = d.count + 1;
+    });
+    expect(result).toEqual({ count: 6 });
+  });
+
+  it('reads reflect prior writes (nested)', () => {
+    const state = { config: { theme: 'dark' } };
+    const result = produceDraft(state, (d) => {
+      d.config.theme = 'light';
+      // Should read the updated value
+      d.config.theme = d.config.theme + '-mode';
+    });
+    expect(result).toEqual({ config: { theme: 'light-mode' } });
+  });
+
+  // ── Replace then mutate ─────────────────────────────────────────
+
+  it('replace nested object then mutate further', () => {
+    const state = { config: { theme: 'dark', size: 14 } };
+    const result = produceDraft(state, (d) => {
+      d.config = { theme: 'blue', size: 20 };
+      d.config.theme = 'red';
+    });
+    expect(result).toEqual({ config: { theme: 'red', size: 20 } });
+  });
+
+  // ── Original immutability ───────────────────────────────────────
+
+  it('never mutates original state', () => {
+    const state = Object.freeze({ count: 0, name: 'test' });
+    const result = produceDraft(state, (d) => {
+      d.count = 5;
+      d.name = 'updated';
+    });
+    expect(result).toEqual({ count: 5, name: 'updated' });
+    expect(state.count).toBe(0);
+    expect(state.name).toBe('test');
+  });
+
+  it('never mutates original nested objects', () => {
+    const config = Object.freeze({ theme: 'dark', size: 14 });
+    const state = Object.freeze({ config });
+    const result = produceDraft(state, (d) => {
+      d.config.theme = 'light';
+    });
+    expect(result).toEqual({ config: { theme: 'light', size: 14 } });
+    expect(config.theme).toBe('dark');
+  });
+
+  // ── Non-POJO pass-through ───────────────────────────────────────
+
+  it('does not proxy Date objects', () => {
+    const date = new Date('2024-01-01');
+    const state = { created: date, name: 'test' };
+    const result = produceDraft(state, (d) => {
+      d.name = 'updated';
+    });
+    expect(result).toEqual({ name: 'updated' });
+  });
+
+  it('does not proxy class instances', () => {
+    class Foo {
+      value = 1;
+    }
+    const foo = new Foo();
+    const state = { foo, name: 'test' };
+
+    // Reading a class instance returns the original
+    produceDraft(state, (d) => {
+      expect(d.foo).toBe(foo);
+    });
+  });
+
+  it('does not proxy arrays (returns frozen copy in DEV)', () => {
+    const items = [1, 2, 3];
+    const state = { items, name: 'test' };
+
+    produceDraft(state, (d) => {
+      // In DEV, arrays are returned as frozen copies to catch mutation attempts
+      expect(d.items).toEqual(items);
+      expect(d.items).not.toBe(items);
+      expect(Object.isFrozen(d.items)).toBe(true);
+    });
+  });
+
+  it('handles array replacement via assignment', () => {
+    const state = { items: [1, 2, 3] };
+    const result = produceDraft(state, (d) => {
+      d.items = [...d.items, 4];
+    });
+    expect(result).toEqual({ items: [1, 2, 3, 4] });
+    expect(state.items).toEqual([1, 2, 3]); // Original unchanged
+  });
+
+  it('handles nested array replacement via assignment', () => {
+    const state = { config: { tags: ['a', 'b'] } };
+    const result = produceDraft(state, (d) => {
+      d.config.tags = [...(d.config as any).tags, 'c'];
+    });
+    expect(result!.config).toEqual({ tags: ['a', 'b', 'c'] });
+  });
+
+  // ── Spread and destructure ─────────────────────────────────────
+
+  it('Object.keys works on draft', () => {
+    const state = { a: 1, b: 2, c: 3 };
+    produceDraft(state, (d) => {
+      expect(Object.keys(d)).toEqual(['a', 'b', 'c']);
+    });
+  });
+
+  it('spread works on draft', () => {
+    const state = { a: 1, b: 2 };
+    produceDraft(state, (d) => {
+      const copy = { ...d };
+      expect(copy).toEqual({ a: 1, b: 2 });
+    });
+  });
+
+  it('destructure works on draft', () => {
+    const state = { a: 1, b: 2 };
+    produceDraft(state, (d) => {
+      const { a, b } = d;
+      expect(a).toBe(1);
+      expect(b).toBe(2);
+    });
+  });
+
+  it('"in" operator works on draft', () => {
+    const state = { a: 1, b: 2 };
+    produceDraft(state, (d) => {
+      expect('a' in d).toBe(true);
+      expect('c' in d).toBe(false);
+    });
+  });
+
+  // ── Null and undefined values ───────────────────────────────────
+
+  it('handles null values in state', () => {
+    const state = { user: null as string | null, count: 0 };
+    const result = produceDraft(state, (d) => {
+      d.user = 'alice';
+    });
+    expect(result).toEqual({ user: 'alice' });
+  });
+
+  it('handles setting value to null', () => {
+    const state = { user: 'alice' as string | null };
+    const result = produceDraft(state, (d) => {
+      d.user = null;
+    });
+    expect(result).toEqual({ user: null });
+  });
+
+  it('handles undefined values in state', () => {
+    const state = { value: undefined as string | undefined, count: 0 };
+    const result = produceDraft(state, (d) => {
+      d.value = 'hello';
+    });
+    expect(result).toEqual({ value: 'hello' });
+  });
+
+  // ── Mixed scenarios ─────────────────────────────────────────────
+
+  it('handles mix of flat and nested mutations', () => {
+    const state = { count: 0, config: { theme: 'dark' } };
+    const result = produceDraft(state, (d) => {
+      d.count = 1;
+      d.config.theme = 'light';
+    });
+    expect(result).toEqual({ count: 1, config: { theme: 'light' } });
+  });
+
+  it('returns null when nested writes result in same values', () => {
+    const state = { config: { theme: 'dark', size: 14 } };
+    const result = produceDraft(state, (d) => {
+      d.config.theme = 'light';
+      d.config.theme = 'dark'; // revert
+    });
+    // Config was copied (write happened) but final values are same as state.config
+    // However, the copy is a new reference, so it's detected as changed
+    // This is expected — same-ref check is at the produceDraft level
+    expect(result).toEqual({ config: { theme: 'dark', size: 14 } });
+  });
+
+  it('structural sharing: unchanged top-level objects keep identity', () => {
+    const obj1 = { x: 1 };
+    const obj2 = { y: 2 };
+    const state = { a: obj1, b: obj2, c: 3 };
+    const result = produceDraft(state, (d) => {
+      d.c = 4;
+    });
+    // Only 'c' changed — 'a' and 'b' are not in the result at all
+    expect(result).toEqual({ c: 4 });
+    expect(result).not.toHaveProperty('a');
+    expect(result).not.toHaveProperty('b');
+  });
+
+  it('structural sharing: nested unchanged siblings keep same reference', () => {
+    const sibling = { data: [1, 2, 3] };
+    const state = { parent: { changed: { value: 1 }, unchanged: sibling } };
+    const result = produceDraft(state, (d) => {
+      d.parent.changed.value = 2;
+    });
+    // The parent object is new (child was modified), but unchanged sibling kept reference
+    expect((result!.parent as any).unchanged).toBe(sibling);
+  });
+
+  // ── Object.create(null) support ─────────────────────────────────
+
+  it('handles objects with null prototype', () => {
+    const config = Object.create(null);
+    config.theme = 'dark';
+    config.size = 14;
+    const state = { config, count: 0 };
+
+    const result = produceDraft(state, (d) => {
+      d.config.theme = 'light';
+    });
+    expect(result!.config).toEqual({ theme: 'light', size: 14 });
+  });
+
+  // ── DEV array guard ─────────────────────────────────────────────
+
+  it('DEV: array mutation methods throw instead of silently mutating', () => {
+    const state = { items: [1, 2, 3] };
+    produceDraft(state, (d) => {
+      const items = d.items;
+      expect(() => (items as number[]).push(4)).toThrow();
+    });
+    // Original was never mutated
+    expect(state.items).toEqual([1, 2, 3]);
+  });
+
+  it('DEV: nested array mutation methods throw', () => {
+    const state = { config: { tags: ['a', 'b'] } };
+    produceDraft(state, (d) => {
+      const tags = d.config.tags;
+      expect(() => (tags as string[]).push('c')).toThrow();
+    });
+    expect(state.config.tags).toEqual(['a', 'b']);
+  });
+});
+
+// ── resolveDraftUpdater ─────────────────────────────────────────
+
+describe('resolveDraftUpdater', () => {
+  it('handles draft mode (void return)', () => {
+    const state = { count: 0, name: 'test' };
+    const result = resolveDraftUpdater(state, (d) => {
+      d.count = 5;
+    });
+    expect(result).toEqual({ count: 5 });
+  });
+
+  it('handles updater mode (explicit return)', () => {
+    const state = { count: 0, name: 'test' };
+    const result = resolveDraftUpdater(state, () => ({ count: 5 }));
+    expect(result).toEqual({ count: 5 });
+  });
+
+  it('returns null for no-op draft', () => {
+    const state = { count: 0 };
+    const result = resolveDraftUpdater(state, (d) => {
+      d.count = 0; // same value
+    });
+    expect(result).toBeNull();
+  });
+
+  it('explicit return takes precedence over draft mutations', () => {
+    const state = { count: 0, name: 'test' };
+    const result = resolveDraftUpdater(state, (d) => {
+      d.count = 99; // draft mutation — ignored
+      return { name: 'updated' }; // explicit return wins
+    });
+    expect(result).toEqual({ name: 'updated' });
+  });
+});

package/src/produceDraft.ts

@@ -0,0 +1,168 @@
+const __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;
+
+/**
+ * Checks if a value is a plain object (POJO).
+ * Returns false for arrays, Dates, class instances, null, etc.
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object') return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+interface DraftNode<T extends object = object> {
+  proxy: T;
+  changed(): boolean;
+  finalize(): T;
+}
+
+function createDraftNode<T extends object>(original: Readonly<T>): DraftNode<T> {
+  let copy: Record<string, unknown> | null = null;
+  const children = new Map<string, DraftNode>();
+
+  function ensureCopy(): Record<string, unknown> {
+    if (!copy) copy = { ...(original as Record<string, unknown>) };
+    return copy;
+  }
+
+  // Use empty object as proxy target to avoid invariant violations
+  // with frozen state objects. All reads/writes go through the handler.
+  const proxy = new Proxy({} as T, {
+    get(_, prop) {
+      if (typeof prop === 'symbol') return (original as any)[prop];
+
+      const key = prop as string;
+
+      // Return cached child draft proxy
+      if (children.has(key)) return children.get(key)!.proxy;
+
+      // Read from copy (if mutated) or original
+      const source: any = copy ?? original;
+      const value = source[key];
+
+      // Auto-draft nested plain objects
+      if (isPlainObject(value)) {
+        const child = createDraftNode(value as Record<string, unknown>);
+        children.set(key, child);
+        return child.proxy;
+      }
+
+      // DEV: freeze arrays so mutation methods (push, splice) throw immediately
+      // instead of silently mutating the original state
+      if (__DEV__ && Array.isArray(value)) {
+        return Object.freeze([...value]);
+      }
+
+      return value;
+    },
+
+    set(_, prop, value) {
+      if (typeof prop === 'symbol') return true;
+
+      const key = prop as string;
+      const source: any = copy ?? original;
+
+      if (source[key] !== value) {
+        ensureCopy();
+        copy![key] = value;
+        // Discard child draft — value was fully replaced
+        children.delete(key);
+      }
+      return true;
+    },
+
+    ownKeys() {
+      return Reflect.ownKeys((copy ?? original) as object);
+    },
+
+    getOwnPropertyDescriptor(_, prop) {
+      const source = (copy ?? original) as Record<string, unknown>;
+      if (Object.prototype.hasOwnProperty.call(source, prop)) {
+        return { value: source[prop as string], writable: true, enumerable: true, configurable: true };
+      }
+      return undefined;
+    },
+
+    has(_, prop) {
+      return prop in ((copy ?? original) as object);
+    },
+  });
+
+  return {
+    proxy,
+
+    changed(): boolean {
+      if (copy) return true;
+      for (const child of children.values()) {
+        if (child.changed()) return true;
+      }
+      return false;
+    },
+
+    finalize(): T {
+      // Merge child results bottom-up
+      for (const [key, child] of children) {
+        if (child.changed()) {
+          ensureCopy();
+          copy![key] = child.finalize();
+        }
+      }
+      return (copy ?? original) as T;
+    },
+  };
+}
+
+/**
+ * Creates a copy-on-write draft proxy of the given state, runs the mutator,
+ * and returns only the changed top-level keys as a Partial.
+ * Returns null if nothing was modified.
+ *
+ * - Nested plain objects use copy-on-write structural sharing
+ * - Same-value assignments are no-ops
+ * - Reads reflect prior writes within the same draft
+ * - Only POJOs are proxied; class instances, arrays, Dates pass through as-is
+ * - Arrays must be replaced via assignment, not mutated in place
+ */
+export function produceDraft<S extends object>(
+  state: Readonly<S>,
+  mutator: (draft: S) => void,
+): Partial<S> | null {
+  const root = createDraftNode(state);
+  mutator(root.proxy);
+
+  if (!root.changed()) return null;
+
+  const finalized = root.finalize();
+
+  // Extract only changed top-level keys
+  const partial: Record<string, unknown> = {};
+  let hasChanges = false;
+
+  for (const key of Object.keys(finalized)) {
+    if ((finalized as any)[key] !== (state as any)[key]) {
+      partial[key] = (finalized as any)[key];
+      hasChanges = true;
+    }
+  }
+
+  return hasChanges ? (partial as Partial<S>) : null;
+}
+
+/**
+ * Resolves a function-form updater through produceDraft.
+ * Handles both patterns: explicit return (existing updater) and void return (draft mode).
+ * Returns the partial to apply, or null if nothing changed.
+ */
+export function resolveDraftUpdater<S extends object>(
+  state: Readonly<S>,
+  updater: (stateOrDraft: S) => Partial<S> | void,
+): Partial<S> | null {
+  let explicitReturn: Partial<S> | undefined;
+  const draftChanges = produceDraft<S>(state, (draft) => {
+    const result = updater(draft);
+    if (result !== undefined && result !== null && typeof result === 'object') {
+      explicitReturn = result;
+    }
+  });
+  return explicitReturn ?? draftChanges;
+}

package/src/react/components/CardList.md

@@ -0,0 +1,97 @@
+# CardList
+
+Headless, unstyled list/grid component for rendering item collections.
+
+---
+
+## When to Use
+
+Use CardList for non-tabular data displays — card grids, article lists, comment threads. It renders semantic HTML (`<ul role="list">`) with data attributes for styling hooks. Compose with `InfiniteScroll` for infinite loading.
+
+---
+
+## Basic Usage
+
+```tsx
+import { CardList } from 'mvc-kit/react';
+
+function PostList() {
+  const [, vm] = useLocal(PostsVM, {});
+  return (
+    <CardList
+      items={vm.items}
+      renderItem={post => <PostCard post={post} />}
+      layout="grid"
+      columns={3}
+    />
+  );
+}
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `T[]` | *required* | Array of data items |
+| `renderItem` | `(item: T, index: number) => ReactNode` | *required* | Item renderer |
+| `keyOf` | `(item: T) => string \| number` | `item => item.id` | Key extractor |
+| `layout` | `'list' \| 'grid'` | `'list'` | Layout mode |
+| `columns` | `number` | `3` | Grid columns (grid mode only) |
+| `gap` | `string` | `'1rem'` | Gap between items (grid mode only) |
+| `loading` | `boolean` | — | Loading state |
+| `error` | `string \| null` | — | Error message |
+| `className` | `string` | — | Container class |
+| `aria-label` | `string` | — | Accessibility label |
+
+### Render Slots
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `renderEmpty` | `() => ReactNode` | Empty state |
+| `renderLoading` | `() => ReactNode` | Loading state |
+| `renderError` | `(error: string) => ReactNode` | Error state |
+
+---
+
+## Grid Layout
+
+Grid mode uses CSS Grid with custom properties for easy override:
+
+```css
+[data-component="card-list"][data-layout="grid"] {
+  /* Override defaults */
+  --card-list-columns: 4;
+  --card-list-gap: 2rem;
+}
+```
+
+---
+
+## Data Attributes
+
+| Attribute | Element | Description |
+|-----------|---------|-------------|
+| `data-component="card-list"` | `<ul>` | Component identifier |
+| `data-layout="list\|grid"` | `<ul>` | Current layout mode |
+| `data-index` | `<li>` | Item index in the array |
+
+---
+
+## Composition with InfiniteScroll
+
+```tsx
+<InfiniteScroll
+  hasMore={vm.hasMore}
+  loading={vm.async.loadMore?.loading}
+  onLoadMore={() => vm.loadMore()}
+>
+  <CardList
+    items={vm.items}
+    renderItem={post => <PostCard post={post} />}
+    layout="grid"
+    columns={2}
+  />
+</InfiniteScroll>
+```