@sigil-dev/runtime 0.9.3 → 0.9.4

package/index.test.ts

@@ -10,6 +10,8 @@ import {
 	createMemo,
 	createProfilerEffect,
 	createRawSignal,
+	createResource,
+	createRoot,
 	createSignal,
 	easeInCubic,
 	easeInOutCubic,
@@ -34,8 +36,10 @@ import {
 	snapshot,
 	tick,
 	tracking,
+	untrack,
 	withEffectScope,
 } from "./index.ts";
+import { mountTransition, removeAnimated } from "./transition.ts";
 
 // Minimal DOM mock for reconcile tests
 class MockNode {
@@ -233,10 +237,13 @@ describe("Runtime", () => {
 
 		test("moves nodes to new order", () => {
 			const { parent, anchor, keyMap } = setup();
+			const i1 = { id: 1 };
+			const i2 = { id: 2 };
+			const i3 = { id: 3 };
 			mockReconcile(
 				anchor,
 				keyMap,
-				[{ id: 1 }, { id: 2 }, { id: 3 }],
+				[i1, i2, i3],
 				(i) => i.id,
 				(i) => new MockElement(`n${i.id}`),
 			);
@@ -247,7 +254,7 @@ describe("Runtime", () => {
 			mockReconcile(
 				anchor,
 				keyMap,
-				[{ id: 3 }, { id: 2 }, { id: 1 }],
+				[i3, i2, i1],
 				(i) => i.id,
 				(i) => new MockElement(`n${i.id}`),
 			);
@@ -258,12 +265,38 @@ describe("Runtime", () => {
 			expect(nodeNames(parent)).toEqual(["n3", "n2", "n1"]);
 		});
 
+		test("rebuilds node when item instance changes under same key", () => {
+			const { parent, anchor, keyMap } = setup();
+			mockReconcile(
+				anchor,
+				keyMap,
+				[{ id: 1, text: "old" }],
+				(i) => i.id,
+				(i) => new MockElement(i.text),
+			);
+			const oldNode = keyMap.get(1);
+
+			// immutable-style update: same key, fresh object → node must swap
+			mockReconcile(
+				anchor,
+				keyMap,
+				[{ id: 1, text: "new" }],
+				(i) => i.id,
+				(i) => new MockElement(i.text),
+			);
+
+			expect(keyMap.get(1)).not.toBe(oldNode);
+			expect(nodeNames(parent)).toEqual(["new"]);
+		});
+
 		test("handles mixed add/remove/reorder", () => {
 			const { parent, anchor, keyMap } = setup();
+			const i1 = { id: 1 };
+			const i3 = { id: 3 };
 			mockReconcile(
 				anchor,
 				keyMap,
-				[{ id: 1 }, { id: 2 }, { id: 3 }],
+				[i1, { id: 2 }, i3],
 				(i) => i.id,
 				(i) => new MockElement(`n${i.id}`),
 			);
@@ -273,7 +306,7 @@ describe("Runtime", () => {
 			mockReconcile(
 				anchor,
 				keyMap,
-				[{ id: 4 }, { id: 3 }, { id: 1 }],
+				[{ id: 4 }, i3, i1],
 				(i) => i.id,
 				(i) => new MockElement(`n${i.id}`),
 			);
@@ -1616,3 +1649,195 @@ describe("Array reactivity", () => {
 		expect(len).toBe(2);
 	});
 });
+
+describe("untrack", () => {
+	test("reading a signal inside untrack does not register a dep", async () => {
+		const tracked = createSignal(0);
+		const untracked = createSignal(0);
+		let runs = 0;
+		createEffect(() => {
+			runs++;
+			untrack(() => untracked());
+			tracked();
+		});
+		await tick();
+		expect(runs).toBe(1);
+		untracked.set(99);
+		await tick();
+		expect(runs).toBe(1); // no re-run — read was untracked
+		tracked.set(1);
+		await tick();
+		expect(runs).toBe(2); // still reacts to tracked reads
+	});
+
+	test("returns fn's value", () => {
+		const sig = createSignal(7);
+		expect(untrack(() => sig())).toBe(7);
+		expect(
+			untrack(() => {
+				expect(tracking()).toBe(false);
+				return "direct";
+			}),
+		).toBe("direct");
+	});
+});
+
+describe("createRoot", () => {
+	test("effects inside survive outer scope disposal", async () => {
+		const count = createSignal(0);
+		let runs = 0;
+		let dispose: () => void = () => {};
+		const outerDispose = withEffectScope(() => {
+			createRoot((d) => {
+				dispose = d;
+				createEffect(() => {
+					count();
+					runs++;
+				});
+			});
+		});
+		const afterOuter = runs;
+		count.set(1);
+		await tick();
+		expect(runs).toBe(afterOuter + 1); // root effect still alive
+		dispose();
+		count.set(2);
+		await tick();
+		expect(runs).toBe(afterOuter + 1); // torn down by dispose()
+	});
+
+	test("detached from enclosing scope entirely", async () => {
+		const count = createSignal(0);
+		let runs = 0;
+		const outerDispose = withEffectScope(() => {
+			createRoot(() => {
+				createEffect(() => {
+					count();
+					runs++;
+				});
+			});
+			// no reference kept — detached root leaks by design
+		});
+		outerDispose();
+		await tick();
+		const before = runs;
+		count.set(1);
+		await tick();
+		expect(runs).toBe(before + 1); // invisible to the disposed outer scope
+	});
+});
+
+describe("createResource", () => {
+	test("resolves data and toggles loading", async () => {
+		const res = createResource(async () => "value");
+		expect(res.loading()).toBe(true);
+		await tick();
+		expect(res.data()).toBe("value");
+		expect(res.loading()).toBe(false);
+		expect(res.error()).toBeUndefined();
+	});
+
+	test("source change refetches with new source value", async () => {
+		const src = createSignal(1);
+		const calls: unknown[] = [];
+		const res = createResource(
+			async (s) => {
+				calls.push(s);
+				return s;
+			},
+			() => src(),
+		);
+		await tick();
+		src.set(2);
+		await tick();
+		expect(calls).toEqual([1, 2]);
+		expect(res.data()).toBe(2);
+	});
+
+	test("stale responses are discarded", async () => {
+		const resolvers: Array<(v: number) => void> = [];
+		const src = createSignal(0);
+		const res = createResource(
+			() =>
+				new Promise<number>((r) => {
+					resolvers.push(r);
+				}),
+			() => src(),
+		);
+		await tick(); // request #1 pending
+		src.set(1);
+		await tick(); // request #2 started
+		resolvers[1]!(99); // newer resolves first
+		await tick();
+		expect(res.data()).toBe(99);
+		resolvers[0]!(11); // stale response arrives late
+		await tick();
+		expect(res.data()).toBe(99); // discarded
+	});
+
+	test("rejection captured in error()", async () => {
+		const res = createResource(async () => {
+			throw new Error("boom");
+		});
+		await tick();
+		expect(res.error()?.message).toBe("boom");
+		expect(res.loading()).toBe(false);
+	});
+
+	test("refetch re-runs the fetcher", async () => {
+		let calls = 0;
+		const res = createResource(async () => {
+			calls++;
+			return calls;
+		});
+		await tick();
+		res.refetch();
+		await tick();
+		expect(res.data()).toBe(2);
+	});
+});
+
+describe("transition directives (runtime)", () => {
+	test("unregistered node is removed synchronously", () => {
+		const el = document.createElement("div");
+		document.body.appendChild(el);
+		removeAnimated(el);
+		expect(el.parentNode).toBeNull();
+	});
+
+	test("out-animation delays removal until finished", async () => {
+		const { promise, resolve } = Promise.withResolvers<void>();
+		const el = document.createElement("div");
+		document.body.appendChild(el);
+		const cleanup = mountTransition(
+			el,
+			((_el: unknown, _params: unknown, direction: "in" | "out") => {
+				expect(direction).toBe("out");
+				return { finished: promise.then(() => undefined) };
+			}) as unknown as Parameters<typeof mountTransition>[1],
+			"out",
+		);
+		removeAnimated(el);
+		expect(el.parentNode).not.toBeNull(); // waiting for the animation
+		resolve();
+		await promise;
+		await tick();
+		expect(el.parentNode).toBeNull(); // removed after finish
+		cleanup();
+	});
+
+	test("in kind plays immediately, transition registers and plays", () => {
+		const played: string[] = [];
+		const fn = ((_el: Element, _p: unknown, d: "in" | "out") => {
+			played.push(d);
+		}) as never;
+		mountTransition(document.createElement("div"), fn, "in");
+		expect(played).toEqual(["in"]);
+		const el = document.createElement("div");
+		mountTransition(el, fn, "transition");
+		expect(played).toEqual(["in", "in"]);
+		removeAnimated(el); // registered → out plays, then removal
+		expect(played).toEqual(["in", "in", "out"]);
+		expect(el.parentNode).toBeNull();
+	});
+});

package/index.ts

@@ -20,6 +20,7 @@ export {
 } from "./easing.ts";
 export { ReactiveMap } from "./reactivity/map.ts";
 export { ReactiveSet } from "./reactivity/set.ts";
+export { mountTransition, removeAnimated } from "./transition.ts";
 
 export const SIGIL_SAFE = Symbol.for("sigil.safe");
 export class SafeHtml {
@@ -142,6 +143,9 @@ function createReactiveProxy<T extends object>(target: T): T {
 						trigger(target, k);
 					}
 					if (Array.isArray(target)) {
+						// delete leaves holes — length must shrink to the new value's,
+						// or iteration (spread, reconcile) sees phantom trailing slots
+						target.length = (newValue as unknown[]).length;
 						trigger(target, "length");
 					}
 				};
@@ -287,6 +291,23 @@ export function tracking(): boolean {
 	return currentEffect !== null;
 }
 
+/**
+ * Run fn() outside of any reactive context: signal reads inside fn() do not
+ * register dependencies on the enclosing effect.
+ */
+export function untrack<T>(fn: () => T): T {
+	const prevEffect = currentEffect;
+	const prevDeps = currentDeps;
+	currentEffect = null;
+	currentDeps = null;
+	try {
+		return fn();
+	} finally {
+		currentEffect = prevEffect;
+		currentDeps = prevDeps;
+	}
+}
+
 // A4: $inspect — dev-only effect logging
 export function createInspectEffect(
 	getValues: () => unknown[],
@@ -417,12 +438,133 @@ export function withEffectScope(fn: () => void): () => void {
 	};
 }
 
+type EffectScopeGlobal = { __sigilEffectScope?: (() => void)[] };
+
+/**
+ * Run fn() with a detached effect scope. Effects created inside are invisible
+ * to enclosing scopes (the scope array is replaced, not merged) and live until
+ * dispose() is called — for app bootstrap, routers, and long-lived listeners.
+ */
+export function createRoot<T>(fn: (dispose: () => void) => T): T {
+	const g = globalThis as EffectScopeGlobal;
+	const prev = g.__sigilEffectScope;
+	const disposers: (() => void)[] = [];
+	g.__sigilEffectScope = disposers;
+	const dispose = () => {
+		for (const d of disposers.splice(0)) d();
+	};
+	try {
+		return fn(dispose);
+	} finally {
+		g.__sigilEffectScope = prev;
+	}
+}
+
+export interface Resource<T> {
+	data: () => T | undefined;
+	loading: () => boolean;
+	error: () => Error | undefined;
+	refetch: () => void;
+}
+
+/**
+ * Async data source with reactive re-fetching. Re-runs when `source()` changes
+ * or refetch() is called; stale responses are discarded by request id.
+ */
+export function createResource<T>(
+	fetcher: (source: unknown, info: { refetch: () => void }) => Promise<T>,
+	source?: () => unknown,
+): Resource<T> {
+	const data = createSignal<T | undefined>(undefined);
+	const loading = createSignal(true);
+	const error = createSignal<Error | undefined>(undefined);
+	const version = createSignal(0);
+	let requestCount = 0;
+	let versionCounter = 0;
+
+	const refetch = () => {
+		versionCounter++;
+		version.set(versionCounter);
+	};
+
+	createEffect(() => {
+		const src = source?.();
+		version(); // track refetch bumps
+		const id = ++requestCount;
+		loading.set(true);
+		error.set(undefined);
+		fetcher(src, { refetch }).then(
+			(result) => {
+				if (id !== requestCount) return; // stale response
+				data.set(result);
+				loading.set(false);
+			},
+			(err: unknown) => {
+				if (id !== requestCount) return;
+				error.set(err instanceof Error ? err : new Error(String(err)));
+				loading.set(false);
+			},
+		);
+	});
+
+	return { data, loading, error, refetch };
+}
+
 export function createMemo<T>(fn: () => T): Signal<T> {
 	const inner = createSignal<T>(undefined as T);
 	createEffect(() => inner.set(fn()));
 	return inner;
 }
 
+/**
+ * Reconcile a list of keyed DOM nodes.
+ * anchor.before(node) handles both insert and move natively.
+ * @param claimNode - Optional hydration callback. Called with (element, key) for
+ *   server-rendered elements removed from the DOM. Returns the element to use,
+ *   or null to discard.
+ */
+const lastItemFor = new WeakMap<object, unknown>();
+
+export function reconcile<T>(
+	anchor: Partial<Comment>,
+	keyMap: Map<unknown, Node>,
+	newItems: T[],
+	getKey: (item: T, index: number) => unknown,
+	createNode: (item: T) => Node,
+	// is this meant to be unused? claimNode?: (element: Element, key: unknown) => Element | null,
+): void {
+	const newKeys = new Set(newItems.map((item, i) => getKey(item, i)));
+
+	// Remove nodes no longer in list (or claim them for hydration)
+	for (const [key, node] of keyMap) {
+		if (!newKeys.has(key)) {
+			node.parentNode?.removeChild(node);
+			keyMap.delete(key);
+		}
+	}
+
+	// Insert/move in order — anchor.before() handles both cases.
+	// A surviving node whose item instance changed is rebuilt: compiled row
+	// bodies bake item reads at creation time, so immutable-style updates
+	// (new object, same key) must swap the node to show fresh content.
+	for (let i = 0; i < newItems.length; i++) {
+		const item = newItems[i]!;
+		const key = getKey(item, i);
+		let node = keyMap.get(key);
+		if (node && lastItemFor.has(node) && !Object.is(lastItemFor.get(node), item)) {
+			node.parentNode?.removeChild(node);
+			keyMap.delete(key);
+			node = undefined;
+		}
+		if (!node) {
+			node = createNode(item);
+			lastItemFor.set(node, item);
+			keyMap.set(key, node);
+		}
+		anchor.before?.(node);
+	}
+}
+
 /**
  * Claim an existing element from a hydration pool by tag name, or create a new one.
  * Removes the claimed node from the pool array.
@@ -488,43 +630,6 @@ export function claimComment(
 	return comment;
 }
 
-/**
- * Reconcile a list of keyed DOM nodes.
- * anchor.before(node) handles both insert and move natively.
- * @param claimNode - Optional hydration callback. Called with (element, key) for
- *   server-rendered elements removed from the DOM. Returns the element to use,
- *   or null to discard.
- */
-export function reconcile<T>(
-	anchor: Partial<Comment>,
-	keyMap: Map<unknown, Node>,
-	newItems: T[],
-	getKey: (item: T) => unknown,
-	createNode: (item: T) => Node,
-	// is this meant to be unused? claimNode?: (element: Element, key: unknown) => Element | null,
-): void {
-	const newKeys = new Set(newItems.map(getKey));
-
-	// Remove nodes no longer in list (or claim them for hydration)
-	for (const [key, node] of keyMap) {
-		if (!newKeys.has(key)) {
-			node.parentNode?.removeChild(node);
-			keyMap.delete(key);
-		}
-	}
-
-	// Insert/move in order — anchor.before() handles both cases
-	for (const item of newItems) {
-		const key = getKey(item);
-		let node = keyMap.get(key);
-		if (!node) {
-			node = createNode(item);
-			keyMap.set(key, node);
-		}
-		anchor.before?.(node);
-	}
-}
-
 /**
  * Hydrate a keyed list: claim the comment anchor, walk its sibling elements
  * to build a keyMap, then reconcile with signal data.
@@ -535,7 +640,7 @@ export function reconcile<T>(
 export function hydrateKeyedList<T>(
 	nodesVar: ChildNode[],
 	signalItems: T[],
-	getKey: (item: T) => unknown,
+	getKey: (item: T, index: number) => unknown,
 	createNode: (item: T) => Node,
 	parent?: Element,
 ): { anchor: Comment; keyMap: Map<unknown, Node> } {
@@ -564,7 +669,7 @@ export function hydrateKeyedList<T>(
 		// Map claimed elements to keys by index
 		for (let i = 0; i < claimed.length && i < signalItems.length; i++) {
 			//@ts-expect-error i is always in bounds
-			const key = getKey(signalItems[i]);
+			const key = getKey(signalItems[i], i);
 			//@ts-expect-error i is always in bounds
 			keyMap.set(key, claimed[i]);
 		}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@sigil-dev/runtime",
   "module": "index.ts",
   "type": "module",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "Runtime for the Sigil framework",
   "private": false,
   "devDependencies": {

package/transition.ts

@@ -0,0 +1,69 @@
+/**
+ * transition:/in:/out: directive support.
+ *
+ * The compiler lowers `<div transition:fade={fade}>` to
+ * `mountTransition(el, fade, "transition")` (bare expression or
+ * `[fn, params]` tuple), and swaps anchor-mount cleanup's `node.remove()`
+ * for `removeAnimated(node)` so out-directions can play before unmount.
+ */
+
+export type TransitionFn = (
+	el: Element,
+	params: unknown,
+	direction: "in" | "out",
+) => Animation | undefined | void;
+
+const outRegistry = new WeakMap<
+	Element,
+	{ fn: TransitionFn; params: unknown }
+>();
+
+/**
+ * Play an in-animation immediately (when kind includes it) and register the
+ * element for an out-animation on removal (when kind includes that).
+ * Returns a cleanup that unregisters the element.
+ */
+export function mountTransition(
+	el: Element,
+	spec: TransitionFn | [TransitionFn, unknown],
+	kind: "in" | "out" | "transition",
+): () => void {
+	const [fn, params] = Array.isArray(spec) ? spec : [spec, undefined];
+	if (kind === "in" || kind === "transition") {
+		fn(el, params, "in");
+	}
+	if (kind === "out" || kind === "transition") {
+		outRegistry.set(el, { fn, params });
+	}
+	return () => {
+		outRegistry.delete(el);
+	};
+}
+
+/**
+ * Remove a node, playing its registered out-animation first when one exists.
+ * No registration → immediate removal (plain remove() semantics).
+ */
+export function removeAnimated(node: Node): void {
+	if (!(node instanceof Element)) {
+		node.remove();
+		return;
+	}
+	const entry = outRegistry.get(node);
+	if (!entry) {
+		node.remove();
+		return;
+	}
+	const animation = entry.fn(node, entry.params, "out");
+	if (animation?.finished && typeof animation.finished.finally === "function") {
+		animation.finished
+			.finally(() => {
+				node.remove();
+			})
+			.catch(() => {
+				node.remove();
+			});
+	} else {
+		node.remove();
+	}
+}