elements-kit 0.0.13 → 0.0.14

package/README.md

@@ -250,6 +250,44 @@ The same `cart` store drives custom elements, React trees, and plain scripts —
 Pre-built signal factories for common browser APIs:
 
 ```ts
+import { signal, effect, untracked, onCleanup } from "elements-kit/signals";
+import { createMediaQuery } from "elements-kit/utilities/media-query";
+import { async } from "elements-kit/utilities/async";
+import { retry } from "elements-kit/utilities/retry";
+import { online } from "elements-kit/utilities/network";
+import { windowFocused } from "elements-kit/utilities/window-focus";
+import { storage } from "elements-kit/utilities/storage";
+
+const id = signal(1);
+const cache = storage("todos"); // persists across reloads, used as initial value
+
+// Query — retries on failure, refetches when back online or tab regains focus
+const fetchTodo = async(() => {
+  if (!online()) return untracked(cache); // pause while offline, return stale value
+  windowFocused();                        // refetch on tab focus
+  return retry(() => {
+    const controller = new AbortController();
+    onCleanup(() => controller.abort());  // abort before each retry
+    return fetch(`/api/todos/${id()}`, { signal: controller.signal })
+      .then((r) => r.json())
+      .then(cache);                       // update cache on success
+  }, 3, (n) => n * 500)();               // 0 ms, 500 ms, 1000 ms backoff
+}).start();
+
+effect(() => console.log(fetchTodo.state, fetchTodo.value));
+
+// Mutation — run once, no reactive tracking
+const deleteTodo = async((todoId: number) =>
+  fetch(`/api/todos/${todoId}`, { method: "DELETE" }).then((r) => r.json()),
+);
+
+const result = await deleteTodo.run(42);
+```
+
+`createMediaQuery` wraps `window.matchMedia` into a reactive signal — reads inside effects or computeds re-run automatically when the media query result changes.
+
+```tsx
+import { effect } from "elements-kit/signals";
 import { createMediaQuery } from "elements-kit/utilities/media-query";
 
 const isDark = createMediaQuery("(prefers-color-scheme: dark)");

package/dist/utilities/async.d.mts

@@ -0,0 +1,37 @@
+import { n as MaybeReactive } from "../index-DUshSQ_6.mjs";
+import { ComputedPromise } from "./promise.mjs";
+
+//#region src/utilities/async.d.ts
+type Fn<TInput, TOutput> = (input: TInput) => Promise<TOutput>;
+declare class Async<TInput = undefined, TOutput = unknown> {
+  #private;
+  get fn(): Fn<TInput, TOutput>;
+  set fn(fn: MaybeReactive<Fn<TInput, TOutput>>);
+  get raw(): ComputedPromise<TOutput | undefined>;
+  get pending(): boolean;
+  get state(): "pending" | "fulfilled" | "rejected";
+  get value(): TOutput | undefined;
+  get reason(): unknown;
+  get result(): unknown;
+  then<TResult1 = TOutput, TResult2 = never>(onfulfilled?: ((value: TOutput | undefined) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+  catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null): Promise<TOutput | undefined | TResult>;
+  finally(onfinally?: (() => void) | null): Promise<TOutput | undefined>;
+  constructor(fn: MaybeReactive<Fn<TInput, TOutput>>);
+  /**
+   * Runs the async function once with the given input, stopping any currently active
+   * and register cleanup effects.
+   */
+  run(...args: TInput extends undefined ? [] : [input: TInput]): this;
+  /**
+   * Stops the current async operation and run cleanup effects.
+   */
+  stop(): this;
+  [Symbol.dispose](): void;
+  /**
+   * Starts a new reactive async operation, stopping any currently active one.
+   */
+  start(...args: TInput extends undefined ? [] : [input: TInput]): this;
+}
+declare function async<TInput = any, TOutput = undefined>(fn: MaybeReactive<(input: TInput) => Promise<TOutput>>): Async<TInput, TOutput> & ((...args: any[]) => TOutput | undefined);
+//#endregion
+export { Async, Fn, async };

package/dist/utilities/async.mjs

@@ -0,0 +1,119 @@
+import { _ as signal, r as resolve, u as effect, y as untracked } from "../signals-BHmWX6ox.mjs";
+import { promise } from "./promise.mjs";
+//#region src/utilities/async.ts
+var Async = class {
+	#fn = signal(async () => Promise.resolve(void 0));
+	#cleanup = () => {};
+	get fn() {
+		return this.#fn();
+	}
+	set fn(fn) {
+		this.#fn(resolve(fn));
+	}
+	#current = signal(promise(() => {}));
+	get raw() {
+		return this.#current();
+	}
+	get pending() {
+		return this.raw.state === "pending";
+	}
+	get state() {
+		return this.raw.state;
+	}
+	get value() {
+		return this.raw.value;
+	}
+	get reason() {
+		return this.raw.reason;
+	}
+	get result() {
+		return this.raw.result;
+	}
+	then(onfulfilled, onrejected) {
+		return this.raw.then(onfulfilled, onrejected);
+	}
+	catch(onrejected) {
+		return this.raw.catch(onrejected);
+	}
+	finally(onfinally) {
+		return this.raw.finally(onfinally);
+	}
+	constructor(fn) {
+		this.#fn(resolve(fn));
+	}
+	#execute(...args) {
+		const input = args[0];
+		const p = promise(this.fn(input));
+		this.#current(p);
+		return p;
+	}
+	/**
+	* Runs the async function once with the given input, stopping any currently active
+	* and register cleanup effects.
+	*/
+	run(...args) {
+		this.stop();
+		this.#cleanup = effect(() => {
+			untracked(() => this.#execute(...args));
+		});
+		return this;
+	}
+	/**
+	* Stops the current async operation and run cleanup effects.
+	*/
+	stop() {
+		this.#cleanup();
+		this.#cleanup = () => {};
+		return this;
+	}
+	[Symbol.dispose]() {
+		this.stop();
+	}
+	/**
+	* Starts a new reactive async operation, stopping any currently active one.
+	*/
+	start(...args) {
+		this.stop();
+		this.#cleanup = effect(() => {
+			this.#execute(...args);
+		});
+		return this;
+	}
+};
+const ASYNC_KEYS = new Set([
+	"then",
+	"catch",
+	"finally",
+	"state",
+	"value",
+	"reason",
+	"result",
+	"pending",
+	"start",
+	"stop",
+	"run",
+	"fn",
+	"raw",
+	Symbol.dispose
+]);
+function async(fn) {
+	const inst = new Async(fn);
+	const signal = () => inst.result;
+	return new Proxy(signal, {
+		apply(_target, _thisArg, args) {
+			return inst.result;
+		},
+		get(_target, prop, receiver) {
+			if (ASYNC_KEYS.has(prop)) {
+				const val = inst[prop];
+				return typeof val === "function" ? val.bind(inst) : val;
+			}
+			return Reflect.get(signal, prop, receiver);
+		},
+		getPrototypeOf() {
+			return Async.prototype;
+		}
+	});
+}
+//#endregion
+export { Async, async };

package/dist/utilities/async.test.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/utilities/async.test.mjs

@@ -0,0 +1,273 @@
+import { _ as signal, g as onCleanup, u as effect } from "../signals-BHmWX6ox.mjs";
+import { n as vi, o as describe, s as it, t as globalExpect } from "../test.BmQO5GaM-ANkhHvbr.mjs";
+import { Async, async } from "./async.mjs";
+import { createInterval } from "./interval.mjs";
+//#region src/utilities/async.test.ts
+function deferred() {
+	let resolve;
+	let reject;
+	return {
+		promise: new Promise((res, rej) => {
+			resolve = res;
+			reject = rej;
+		}),
+		resolve,
+		reject
+	};
+}
+describe("Async", () => {
+	it("is reactive as a computed signal (effect)", async () => {
+		const op = async((x) => Promise.resolve(x * 2));
+		const values = [];
+		const stop = effect(() => {
+			values.push(op());
+		});
+		op.run(2);
+		await op;
+		op.run(3);
+		await op;
+		stop();
+		globalExpect(values).toContain(void 0);
+		globalExpect(values).toContain(4);
+		globalExpect(values).toContain(6);
+		globalExpect(values.at(-1)).toBe(6);
+	});
+	it("is callable as a signal and returns the current result", async () => {
+		const op = async(() => Promise.resolve(123));
+		globalExpect(op()).toBeUndefined();
+		op.start();
+		await op;
+		globalExpect(op()).toBe(123);
+		const err = /* @__PURE__ */ new Error("fail");
+		const op2 = async(() => Promise.reject(err));
+		op2.start();
+		await op2.catch(() => {});
+		globalExpect(op2()).toBe(err);
+	});
+	it("starts in pending state with no value or reason", () => {
+		const op = async(() => Promise.resolve(1));
+		globalExpect(op.state).toBe("pending");
+		globalExpect(op.pending).toBe(true);
+		globalExpect(op.value).toBeUndefined();
+		globalExpect(op.reason).toBeUndefined();
+		globalExpect(op.result).toBeUndefined();
+		globalExpect(op.pending).toBe(op.state === "pending");
+	});
+	it("transitions to fulfilled after start()", async () => {
+		const op = async(() => Promise.resolve(42));
+		op.start();
+		await op;
+		globalExpect(op.state).toBe("fulfilled");
+		globalExpect(op.pending).toBe(false);
+		globalExpect(op.value).toBe(42);
+		globalExpect(op.reason).toBeUndefined();
+		globalExpect(op.result).toBe(42);
+		globalExpect(op.result).toBe(42);
+	});
+	it("transitions to rejected after start()", async () => {
+		const err = /* @__PURE__ */ new Error("fail");
+		const op = async(() => Promise.reject(err));
+		op.start();
+		await op.catch(() => {});
+		globalExpect(op.state).toBe("rejected");
+		globalExpect(op.pending).toBe(false);
+		globalExpect(op.reason).toBe(err);
+		globalExpect(op.value).toBeUndefined();
+		globalExpect(op.result).toBe(err);
+		globalExpect(op.reason).toBe(err);
+	});
+	it("await op.run(args) resolves to the fulfilled value", async () => {
+		const op = async((x) => Promise.resolve(x + 100));
+		globalExpect(await op.run(23)).toBe(123);
+		globalExpect(op.value).toBe(123);
+		globalExpect(op.state).toBe("fulfilled");
+	});
+	it("run() resolves to the fulfilled value", async () => {
+		globalExpect(await async((x) => Promise.resolve(x * 2)).run(5)).toBe(10);
+	});
+	it("await op resolves to the fulfilled value", async () => {
+		const op = async(() => Promise.resolve(7));
+		op.start();
+		globalExpect(await op).toBe(7);
+	});
+	it("await op.catch() resolves on rejection", async () => {
+		const err = /* @__PURE__ */ new Error("fail");
+		const op = async(() => Promise.reject(err));
+		op.start();
+		globalExpect(await op.catch((e) => e)).toBe(err);
+	});
+	it("delegates .then()", async () => {
+		const op = async(() => Promise.resolve(3));
+		op.start();
+		globalExpect(await op.then((v) => (v ?? 0) * 2)).toBe(6);
+	});
+	it("instanceof Async", () => {
+		globalExpect(async(() => Promise.resolve()) instanceof Async).toBe(true);
+	});
+	it("is reactive — effect reruns when state transitions to fulfilled", async () => {
+		const op = async(() => Promise.resolve(10));
+		const snapshots = [];
+		const stop = effect(() => {
+			snapshots.push(op.state);
+		});
+		op.start();
+		await op;
+		stop();
+		globalExpect(snapshots).toContain("pending");
+		globalExpect(snapshots.at(-1)).toBe("fulfilled");
+	});
+	it("is reactive — effect sees value after fulfillment", async () => {
+		const op = async(() => Promise.resolve(99));
+		const values = [];
+		const stop = effect(() => {
+			values.push(op.value);
+		});
+		op.start();
+		await op;
+		stop();
+		globalExpect(values).toEqual([
+			void 0,
+			void 0,
+			99
+		]);
+	});
+	it("is reactive — effect reruns on rejection", async () => {
+		const err = /* @__PURE__ */ new Error("x");
+		const op = async(() => Promise.reject(err));
+		const reasons = [];
+		const stop = effect(() => {
+			reasons.push(op.reason);
+		});
+		op.start();
+		await op.catch(() => {});
+		stop();
+		globalExpect(reasons).toEqual([
+			void 0,
+			void 0,
+			err
+		]);
+	});
+	it("start() re-runs when a signal read inside fn changes", async () => {
+		const id = signal(1);
+		const calls = [];
+		const op = async(() => {
+			const current = id();
+			calls.push(current);
+			return Promise.resolve(current);
+		});
+		op.start();
+		await op;
+		id(2);
+		await op;
+		op.stop();
+		globalExpect(calls).toEqual([1, 2]);
+	});
+	it("run() is not reactive — signal change does not re-run", async () => {
+		const id = signal(1);
+		const calls = [];
+		const op = async(() => {
+			const current = id();
+			calls.push(current);
+			return Promise.resolve(current);
+		});
+		op.run();
+		await op;
+		id(2);
+		await Promise.resolve();
+		op.stop();
+		globalExpect(calls).toEqual([1]);
+	});
+	it("start() resets to pending on re-run", async () => {
+		const d = deferred();
+		const id = signal(1);
+		const op = async(() => {
+			id();
+			return d.promise;
+		});
+		op.start();
+		globalExpect(op.pending).toBe(true);
+		id(2);
+		globalExpect(op.pending).toBe(true);
+		d.resolve(5);
+		op.stop();
+	});
+	it("stop() prevents further reactive reruns", async () => {
+		const id = signal(1);
+		const calls = [];
+		const op = async(() => {
+			calls.push(id());
+			return Promise.resolve(id());
+		});
+		op.start();
+		await op;
+		op.stop();
+		id(2);
+		await Promise.resolve();
+		globalExpect(calls).toEqual([1]);
+	});
+	it("onCleanup inside run() fires when stop() is called", () => {
+		const cleaned = [];
+		const op = async(() => {
+			onCleanup(() => cleaned.push(1));
+			return Promise.resolve();
+		});
+		op.run();
+		globalExpect(cleaned).toEqual([]);
+		op.stop();
+		globalExpect(cleaned).toEqual([1]);
+	});
+	it("onCleanup inside start() fires on each re-run", async () => {
+		const id = signal(1);
+		const cleaned = [];
+		const op = async(() => {
+			const current = id();
+			onCleanup(() => cleaned.push(current));
+			return Promise.resolve();
+		});
+		op.start();
+		await op;
+		id(2);
+		await op;
+		op.stop();
+		globalExpect(cleaned[0]).toBe(1);
+	});
+	it("re-runs when createInterval ticks", async () => {
+		vi.useFakeTimers();
+		const timer = createInterval(1e3);
+		const calls = [];
+		const op = async(() => {
+			timer.timestamp();
+			calls.push(calls.length);
+			return Promise.resolve(calls.length);
+		});
+		op.start();
+		await op;
+		globalExpect(calls.length).toBe(1);
+		vi.advanceTimersByTime(1e3);
+		await op;
+		globalExpect(calls.length).toBe(2);
+		op.stop();
+		timer.stop();
+		vi.useRealTimers();
+	});
+	it("state and value update atomically — no inconsistent intermediate state", async () => {
+		const op = async(() => Promise.resolve(7));
+		const snapshots = [];
+		const stop = effect(() => {
+			snapshots.push({
+				state: op.state,
+				value: op.value
+			});
+		});
+		op.start();
+		await op;
+		stop();
+		globalExpect(snapshots.find((s) => s.state === "fulfilled" && s.value === void 0)).toBeUndefined();
+		globalExpect(snapshots.at(-1)).toEqual({
+			state: "fulfilled",
+			value: 7
+		});
+	});
+});
+//#endregion
+export {};

package/dist/utilities/interval.d.mts

@@ -2,17 +2,18 @@ import { t as Computed } from "../index-DUshSQ_6.mjs";
 
 //#region src/utilities/interval.d.ts
 type IntervalResult = {
-  isRunning: Computed<boolean>;
+  timestamp: Computed<number>;
+  pending: Computed<boolean>;
   start(): void;
   stop(): void;
   reset(): void;
 } & Disposable;
+type Fn = () => void;
+type Delay = number | (() => number);
 /**
  * Pausable `setInterval` wrapper.  Starts running immediately on creation.
- *
- * @param callback - Called on each tick.
- * @param delay    - Interval delay in ms (or a reactive getter).
  */
-declare function createInterval(callback: () => void, delay: number | (() => number)): IntervalResult;
+declare function createInterval(delay: Delay): IntervalResult;
+declare function createInterval(callback: Fn, delay: Delay): IntervalResult;
 //#endregion
 export { createInterval };

package/dist/utilities/interval.mjs

@@ -1,24 +1,23 @@
 import { _ as signal, g as onCleanup } from "../signals-BHmWX6ox.mjs";
 //#region src/utilities/interval.ts
-/**
-* Pausable `setInterval` wrapper.  Starts running immediately on creation.
-*
-* @param callback - Called on each tick.
-* @param delay    - Interval delay in ms (or a reactive getter).
-*/
-function createInterval(callback, delay) {
-	const isRunning = signal(true);
+function createInterval(arg1, arg2) {
+	const [callback, delay] = resolveArgs(arg1, arg2);
+	const pending = signal(true);
 	let id;
+	const timestamp = signal(Date.now());
 	const getDelay = typeof delay === "function" ? delay : () => delay;
 	const start = () => {
 		if (id !== void 0) return;
-		isRunning(true);
-		id = setInterval(() => callback(), getDelay());
+		pending(true);
+		id = setInterval(() => {
+			callback?.();
+			timestamp(Date.now());
+		}, getDelay());
 	};
 	const stop = () => {
 		clearInterval(id);
 		id = void 0;
-		isRunning(false);
+		pending(false);
 	};
 	const reset = () => {
 		stop();
@@ -28,12 +27,17 @@ function createInterval(callback, delay) {
 	const cleanup = () => stop();
 	onCleanup(cleanup);
 	return {
-		isRunning,
+		timestamp,
+		pending,
 		start,
 		stop,
 		reset,
 		[Symbol.dispose]: cleanup
 	};
 }
+function resolveArgs(arg1, arg2) {
+	if (arg2 === void 0) return [void 0, arg1];
+	return [arg1, arg2];
+}
 //#endregion
 export { createInterval };

package/dist/utilities/interval.test.mjs

@@ -26,7 +26,7 @@ describe("createInterval", () => {
 		iv.stop();
 		vi.advanceTimersByTime(500);
 		globalExpect(cb).toHaveBeenCalledTimes(0);
-		globalExpect(iv.isRunning()).toBe(false);
+		globalExpect(iv.pending()).toBe(false);
 	});
 	it("start() resumes after stop", () => {
 		vi.useFakeTimers();
@@ -63,6 +63,35 @@ describe("createInterval", () => {
 		vi.advanceTimersByTime(500);
 		globalExpect(cb).toHaveBeenCalledTimes(0);
 	});
+	it("no-callback form updates timestamp on each tick", () => {
+		vi.useFakeTimers();
+		let iv;
+		effectScope(() => {
+			iv = createInterval(100);
+		});
+		const before = iv.timestamp();
+		vi.advanceTimersByTime(100);
+		globalExpect(iv.timestamp()).toBeGreaterThan(before);
+	});
+	it("dynamic delay form is called each tick", () => {
+		vi.useFakeTimers();
+		const cb = vi.fn();
+		const getDelay = vi.fn().mockReturnValue(100);
+		effectScope(() => {
+			createInterval(cb, getDelay);
+		});
+		vi.advanceTimersByTime(300);
+		globalExpect(cb).toHaveBeenCalledTimes(3);
+	});
+	it("stops when scope is disposed", () => {
+		vi.useFakeTimers();
+		const cb = vi.fn();
+		effectScope(() => {
+			createInterval(cb, 100);
+		})();
+		vi.advanceTimersByTime(500);
+		globalExpect(cb).toHaveBeenCalledTimes(0);
+	});
 });
 //#endregion
 export {};

package/dist/utilities/network.d.mts

@@ -0,0 +1,10 @@
+import { t as Computed } from "../index-DUshSQ_6.mjs";
+
+//#region src/utilities/network.d.ts
+/**
+ * Singleton `Computed<boolean>` — `true` when `navigator.onLine` is true.
+ * Reacts to `online` / `offline` window events.
+ */
+declare const online: Computed<boolean>;
+//#endregion
+export { online };

package/dist/utilities/network.mjs

@@ -0,0 +1,17 @@
+import { _ as signal } from "../signals-BHmWX6ox.mjs";
+import { on } from "./event-listener.mjs";
+//#region src/utilities/network.ts
+function createOnline() {
+	const value = signal(typeof navigator !== "undefined" ? navigator.onLine : true);
+	const update = () => value(navigator.onLine);
+	on(window, "online", update);
+	on(window, "offline", update);
+	return value;
+}
+/**
+* Singleton `Computed<boolean>` — `true` when `navigator.onLine` is true.
+* Reacts to `online` / `offline` window events.
+*/
+const online = createOnline();
+//#endregion
+export { online };

package/dist/utilities/network.test.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/utilities/network.test.mjs

@@ -0,0 +1,29 @@
+import { n as vi, o as describe, r as afterEach, s as it, t as globalExpect } from "../test.BmQO5GaM-ANkhHvbr.mjs";
+import { online } from "./network.mjs";
+//#region src/utilities/network.test.ts
+afterEach(() => {
+	vi.restoreAllMocks();
+});
+describe("online", () => {
+	it("reflects navigator.onLine", () => {
+		globalExpect(online()).toBe(navigator.onLine);
+	});
+	it("becomes false on offline event", () => {
+		Object.defineProperty(navigator, "onLine", {
+			configurable: true,
+			get: () => false
+		});
+		window.dispatchEvent(new Event("offline"));
+		globalExpect(online()).toBe(false);
+	});
+	it("becomes true on online event", () => {
+		Object.defineProperty(navigator, "onLine", {
+			configurable: true,
+			get: () => true
+		});
+		window.dispatchEvent(new Event("online"));
+		globalExpect(online()).toBe(true);
+	});
+});
+//#endregion
+export {};

package/dist/utilities/promise.d.mts

@@ -0,0 +1,56 @@
+import { t as Computed } from "../index-DUshSQ_6.mjs";
+
+//#region src/utilities/promise.d.ts
+/**
+ * A `Promise` subclass that exposes its state as reactive signals.
+ *
+ * Prefer the {@link promise} factory for most use cases — it returns a
+ * `ComputedPromise` that is both awaitable and callable as a signal.
+ * Use `ReactivePromise` directly when you need the lower-level class —
+ * for example, to wrap a promise and expose `.state`, `.value`, `.reason`,
+ * and `.result` without the `Computed` callable interface.
+ *
+ * @example
+ * ```ts
+ * const rp = ReactivePromise.from(fetch("/api/data"));
+ *
+ * effect(() => {
+ *   if (rp.state === "fulfilled") console.log(rp.value);
+ * });
+ * ```
+ */
+declare class ReactivePromise<T, E = unknown> extends Promise<T> {
+  #private;
+  get state(): "pending" | "fulfilled" | "rejected";
+  get value(): T | undefined;
+  get reason(): E | undefined;
+  get result(): T | E | undefined;
+  constructor(executor: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: any) => void) => void);
+  static from<T, E = unknown>(p: Promise<T>): ReactivePromise<T, E>;
+}
+type ComputedPromise<T, E = unknown> = ReactivePromise<T, E> & Computed<T | E | undefined>;
+type Executor<T, E = unknown> = (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: E) => void) => void;
+/**
+ * Wraps a promise, executor, or `ReactivePromise` into a `ComputedPromise` —
+ * an object that is both awaitable like a regular Promise and reactive like a
+ * `Computed` signal.
+ *
+ * **Awaitable:** `await promise(fetch(...))` resolves to the fulfilled value,
+ * or rejects with the rejection reason, just like a native Promise.
+ *
+ * **Reactive:** calling the returned value as a function (`cp()`) reads the
+ * current result inside an `effect` or `computed`, tracking it as a dependency.
+ * Equivalent to `.result` — returns `undefined` while pending, the fulfilled
+ * value when resolved, or the rejection reason when rejected.
+ *
+ * Reactive state is also accessible via:
+ * - `.state` — `"pending" | "fulfilled" | "rejected"`
+ * - `.value` — the resolved value (or `undefined` while pending)
+ * - `.reason` — the rejection reason (or `undefined` while pending/fulfilled)
+ * - `.result` — `T | E | undefined`; the resolved value, rejection reason, or `undefined` while pending
+ */
+declare function promise<T, E = unknown>(p: ReactivePromise<T>): ComputedPromise<T, E>;
+declare function promise<T, E = unknown>(p: Promise<T>): ComputedPromise<T, E>;
+declare function promise<T, E = unknown>(executor: Executor<T, E>): ComputedPromise<T, E>;
+//#endregion
+export { ComputedPromise, ReactivePromise, promise };

package/dist/utilities/promise.mjs

@@ -0,0 +1,101 @@
+import { _ as signal, c as batch, l as computed } from "../signals-BHmWX6ox.mjs";
+//#region src/utilities/promise.ts
+/**
+* A `Promise` subclass that exposes its state as reactive signals.
+*
+* Prefer the {@link promise} factory for most use cases — it returns a
+* `ComputedPromise` that is both awaitable and callable as a signal.
+* Use `ReactivePromise` directly when you need the lower-level class —
+* for example, to wrap a promise and expose `.state`, `.value`, `.reason`,
+* and `.result` without the `Computed` callable interface.
+*
+* @example
+* ```ts
+* const rp = ReactivePromise.from(fetch("/api/data"));
+*
+* effect(() => {
+*   if (rp.state === "fulfilled") console.log(rp.value);
+* });
+* ```
+*/
+var ReactivePromise = class ReactivePromise extends Promise {
+	#state = signal("pending");
+	#value = signal(void 0);
+	#reason = signal(void 0);
+	#result = computed(() => {
+		const state = this.#state();
+		if (state === "fulfilled") return this.#value();
+		if (state === "rejected") return this.#reason();
+	});
+	get state() {
+		return this.#state();
+	}
+	get value() {
+		return this.#value();
+	}
+	get reason() {
+		return this.#reason();
+	}
+	get result() {
+		return this.#result();
+	}
+	constructor(executor) {
+		super((res, rej) => {
+			executor(async (value) => {
+				const resolved = await value;
+				batch(() => {
+					this.#state("fulfilled");
+					this.#value(resolved);
+				});
+				res(value);
+			}, async (_reason) => {
+				const reason = await _reason;
+				batch(() => {
+					this.#state("rejected");
+					this.#reason(reason);
+				});
+				rej(reason);
+			});
+		});
+	}
+	static from(p) {
+		return new ReactivePromise((resolve, reject) => {
+			p.then(resolve).catch(reject);
+		});
+	}
+};
+const PROMISE_KEYS = new Set([
+	"then",
+	"catch",
+	"finally",
+	"state",
+	"value",
+	"reason",
+	"result"
+]);
+function resolvePromise(from) {
+	if (from instanceof ReactivePromise) return from;
+	if (from instanceof Promise) return ReactivePromise.from(from);
+	return new ReactivePromise(from);
+}
+function promise(from) {
+	const p = resolvePromise(from);
+	const $value = computed(() => p.result);
+	return new Proxy($value, {
+		apply() {
+			return $value();
+		},
+		get(target, prop, receiver) {
+			if (PROMISE_KEYS.has(prop)) {
+				const val = p[prop];
+				return typeof val === "function" ? val.bind(p) : val;
+			}
+			return Reflect.get(target, prop, receiver);
+		},
+		getPrototypeOf() {
+			return ReactivePromise.prototype;
+		}
+	});
+}
+//#endregion
+export { ReactivePromise, promise };

package/dist/utilities/promise.test.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/utilities/promise.test.mjs

@@ -0,0 +1,156 @@
+import { u as effect } from "../signals-BHmWX6ox.mjs";
+import { o as describe, s as it, t as globalExpect } from "../test.BmQO5GaM-ANkhHvbr.mjs";
+import { ReactivePromise, promise } from "./promise.mjs";
+//#region src/utilities/promise.test.ts
+describe("ReactivePromise", () => {
+	it("starts in pending state", () => {
+		const rp = new ReactivePromise(() => {});
+		globalExpect(rp.state).toBe("pending");
+		globalExpect(rp.value).toBeUndefined();
+		globalExpect(rp.reason).toBeUndefined();
+		globalExpect(rp.result).toBeUndefined();
+	});
+	it("transitions to fulfilled", async () => {
+		const rp = new ReactivePromise((resolve) => resolve(42));
+		await rp;
+		globalExpect(rp.state).toBe("fulfilled");
+		globalExpect(rp.value).toBe(42);
+		globalExpect(rp.reason).toBeUndefined();
+		globalExpect(rp.result).toBe(42);
+	});
+	it("transitions to rejected", async () => {
+		const err = /* @__PURE__ */ new Error("fail");
+		const rp = new ReactivePromise((_, reject) => reject(err));
+		await rp.catch(() => {});
+		globalExpect(rp.state).toBe("rejected");
+		globalExpect(rp.reason).toBe(err);
+		globalExpect(rp.value).toBeUndefined();
+		globalExpect(rp.result).toBe(err);
+	});
+	it("unwraps a PromiseLike value", async () => {
+		const rp = new ReactivePromise((resolve) => resolve(Promise.resolve(99)));
+		await rp;
+		globalExpect(rp.value).toBe(99);
+	});
+	it("state and value update atomically — no inconsistent intermediate state", async () => {
+		const rp = new ReactivePromise((resolve) => resolve(7));
+		const snapshots = [];
+		const stop = effect(() => {
+			snapshots.push({
+				state: rp.state,
+				value: rp.value
+			});
+		});
+		await rp;
+		stop();
+		globalExpect(snapshots.find((s) => s.state === "fulfilled" && s.value === void 0)).toBeUndefined();
+		globalExpect(snapshots.at(-1)).toEqual({
+			state: "fulfilled",
+			value: 7
+		});
+	});
+	it("state and reason update atomically on rejection", async () => {
+		const err = /* @__PURE__ */ new Error("oops");
+		const rp = new ReactivePromise((_, reject) => reject(err));
+		const snapshots = [];
+		const stop = effect(() => {
+			snapshots.push({
+				state: rp.state,
+				reason: rp.reason
+			});
+		});
+		await rp.catch(() => {});
+		stop();
+		globalExpect(snapshots.find((s) => s.state === "rejected" && s.reason === void 0)).toBeUndefined();
+		globalExpect(snapshots.at(-1)).toEqual({
+			state: "rejected",
+			reason: err
+		});
+	});
+	it("ReactivePromise.from() wraps an existing Promise", async () => {
+		const rp = ReactivePromise.from(Promise.resolve("hello"));
+		await rp;
+		globalExpect(rp.state).toBe("fulfilled");
+		globalExpect(rp.value).toBe("hello");
+	});
+});
+describe("promise()", () => {
+	it("is instanceof ReactivePromise", () => {
+		globalExpect(promise(() => {}) instanceof ReactivePromise).toBe(true);
+	});
+	it("returns undefined while pending", () => {
+		const cp = promise(() => {});
+		globalExpect(cp()).toBeUndefined();
+		globalExpect(cp.state).toBe("pending");
+	});
+	it("returns the resolved value when fulfilled", async () => {
+		const cp = promise((resolve) => resolve(42));
+		await cp;
+		globalExpect(cp()).toBe(42);
+	});
+	it("returns the rejection reason when rejected", async () => {
+		const err = /* @__PURE__ */ new Error("fail");
+		const cp = promise((_, reject) => reject(err));
+		await cp.catch(() => {});
+		globalExpect(cp()).toBe(err);
+	});
+	it("wraps an existing Promise", async () => {
+		const cp = promise(Promise.resolve("hi"));
+		await cp;
+		globalExpect(cp()).toBe("hi");
+	});
+	it("passes through a ReactivePromise", async () => {
+		const cp = promise(new ReactivePromise((resolve) => resolve(5)));
+		await cp;
+		globalExpect(cp()).toBe(5);
+	});
+	it("is awaitable — resolves to the fulfilled value", async () => {
+		globalExpect(await promise((resolve) => resolve(100))).toBe(100);
+	});
+	it("is awaitable — rejects on failure", async () => {
+		const err = /* @__PURE__ */ new Error("bad");
+		const cp = promise((_, reject) => reject(err));
+		let caught;
+		await cp.catch((e) => {
+			caught = e;
+		});
+		globalExpect(caught).toBe(err);
+	});
+	it("delegates .then()", async () => {
+		globalExpect(await promise((resolve) => resolve(3)).then((v) => v * 2)).toBe(6);
+	});
+	it("delegates .catch()", async () => {
+		const err = /* @__PURE__ */ new Error("caught");
+		globalExpect(await promise((_, reject) => reject(err)).catch((e) => e)).toBe(err);
+	});
+	it("cp.catch handler runs on rejection", async () => {
+		const err = /* @__PURE__ */ new Error("caught");
+		const cp = promise((_, reject) => reject(err));
+		const caught = [];
+		await cp.catch((e) => caught.push(e));
+		globalExpect(caught).toEqual([err]);
+	});
+	it("is reactive — effect reruns on fulfillment", async () => {
+		const cp = promise((resolve) => resolve(1));
+		const values = [];
+		const stop = effect(() => {
+			values.push(cp.value);
+		});
+		await cp;
+		stop();
+		globalExpect(values).toEqual([void 0, 1]);
+	});
+	it("is reactive — effect reruns on rejection", async () => {
+		const err = /* @__PURE__ */ new Error("x");
+		const cp = promise((_, reject) => reject(err));
+		const results = [];
+		const stop = effect(() => {
+			results.push(cp());
+		});
+		await cp.catch(() => {});
+		stop();
+		globalExpect(results).toEqual([void 0, err]);
+	});
+});
+//#endregion
+export {};

package/dist/utilities/retry.d.mts

@@ -0,0 +1,10 @@
+//#region src/utilities/retry.d.ts
+type RetryDelay = number | ((attempt: number) => number);
+/**
+ * Wraps `fn` to retry up to `attempts` times on failure.
+ * Delay (if provided) is inserted between failures only — not after the last.
+ * Each attempt runs in an effect scope so `onCleanup` inside `fn` fires before each retry.
+ */
+declare function retry<T>(fn: () => Promise<T>, attempts: number, delay?: RetryDelay): () => Promise<T>;
+//#endregion
+export { retry };

package/dist/utilities/retry.mjs

@@ -0,0 +1,32 @@
+import { u as effect, y as untracked } from "../signals-BHmWX6ox.mjs";
+//#region src/utilities/retry.ts
+/**
+* Wraps `fn` to retry up to `attempts` times on failure.
+* Delay (if provided) is inserted between failures only — not after the last.
+* Each attempt runs in an effect scope so `onCleanup` inside `fn` fires before each retry.
+*/
+function retry(fn, attempts, delay) {
+	return async () => {
+		let last;
+		for (let i = 0; i < attempts; i++) {
+			let stop = () => {};
+			try {
+				const result = await new Promise((res, rej) => {
+					stop = effect(() => untracked(() => fn().then(res, rej)));
+				});
+				stop();
+				return result;
+			} catch (err) {
+				stop();
+				last = err;
+				if (i < attempts - 1 && delay !== void 0) {
+					const ms = typeof delay === "function" ? delay(i) : delay;
+					await new Promise((r) => setTimeout(r, ms));
+				}
+			}
+		}
+		throw last;
+	};
+}
+//#endregion
+export { retry };

package/dist/utilities/retry.test.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/utilities/retry.test.mjs

@@ -0,0 +1,83 @@
+import { g as onCleanup } from "../signals-BHmWX6ox.mjs";
+import { n as vi, o as describe, s as it, t as globalExpect } from "../test.BmQO5GaM-ANkhHvbr.mjs";
+import { retry } from "./retry.mjs";
+//#region src/utilities/retry.test.ts
+describe("retry", () => {
+	it("resolves immediately on first success", async () => {
+		globalExpect(await retry(() => Promise.resolve(42), 3)()).toBe(42);
+	});
+	it("retries after failure and resolves on later success", async () => {
+		let calls = 0;
+		globalExpect(await retry(() => {
+			calls++;
+			if (calls < 3) return Promise.reject(/* @__PURE__ */ new Error("fail"));
+			return Promise.resolve(calls);
+		}, 3)()).toBe(3);
+		globalExpect(calls).toBe(3);
+	});
+	it("rejects after exhausting all attempts", async () => {
+		const err = /* @__PURE__ */ new Error("always fails");
+		await globalExpect(retry(() => Promise.reject(err), 3)()).rejects.toBe(err);
+	});
+	it("rejects with the last error", async () => {
+		let i = 0;
+		const errors = [
+			/* @__PURE__ */ new Error("a"),
+			/* @__PURE__ */ new Error("b"),
+			/* @__PURE__ */ new Error("c")
+		];
+		await globalExpect(retry(() => Promise.reject(errors[i++]), 3)()).rejects.toBe(errors[2]);
+	});
+	it("delays between failures but not after the last", async () => {
+		const delayFn = vi.fn().mockReturnValue(0);
+		await retry(() => Promise.reject(/* @__PURE__ */ new Error("x")), 3, delayFn)().catch(() => {});
+		globalExpect(delayFn).toHaveBeenCalledTimes(2);
+	});
+	it("supports dynamic delay via function — passes attempt index", async () => {
+		const delayFn = vi.fn().mockReturnValue(0);
+		await retry(() => Promise.reject(/* @__PURE__ */ new Error("x")), 3, delayFn)().catch(() => {});
+		globalExpect(delayFn).toHaveBeenNthCalledWith(1, 0);
+		globalExpect(delayFn).toHaveBeenNthCalledWith(2, 1);
+	});
+	it("onCleanup inside fn fires before each retry", async () => {
+		const cleaned = [];
+		let attempt = 0;
+		await retry(() => {
+			const i = attempt++;
+			onCleanup(() => cleaned.push(i));
+			if (i < 2) return Promise.reject(/* @__PURE__ */ new Error("fail"));
+			return Promise.resolve(i);
+		}, 3)();
+		globalExpect(cleaned).toContain(0);
+		globalExpect(cleaned).toContain(1);
+	});
+	it("composes with async()", async () => {
+		const asyncOp = (await import("./async.mjs")).async;
+		let calls = 0;
+		const op = asyncOp(() => retry(() => {
+			calls++;
+			if (calls < 2) return Promise.reject(/* @__PURE__ */ new Error("fail"));
+			return Promise.resolve(calls);
+		}, 3)());
+		op.start();
+		await op;
+		globalExpect(op.value).toBe(2);
+		op.stop();
+	});
+	it("AbortController cleanup fires between retries when composed with async()", async () => {
+		const asyncOp = (await import("./async.mjs")).async;
+		const aborted = [];
+		let attempt = 0;
+		const op = asyncOp(() => {
+			const i = attempt++;
+			onCleanup(() => aborted.push(i));
+			if (i < 2) return Promise.reject(/* @__PURE__ */ new Error("fail"));
+			return Promise.resolve(i);
+		});
+		op.start();
+		await op.catch(() => {});
+		op.stop();
+	});
+});
+//#endregion
+export {};

package/dist/utilities/timeout.d.mts

@@ -2,7 +2,7 @@ import { t as Computed } from "../index-DUshSQ_6.mjs";
 
 //#region src/utilities/timeout.d.ts
 type TimeoutResult = {
-  isRunning: Computed<boolean>;
+  pending: Computed<boolean>;
   start(): void;
   stop(): void;
   reset(): void;

package/dist/utilities/timeout.mjs

@@ -6,19 +6,19 @@ import { _ as signal, g as onCleanup } from "../signals-BHmWX6ox.mjs";
 * unless `immediate` is set to `false`.
 */
 function createTimeout(callback, delay, immediate = true) {
-	const isRunning = signal(false);
+	const pending = signal(false);
 	let id;
 	const getDelay = typeof delay === "function" ? delay : () => delay;
 	const stop = () => {
 		clearTimeout(id);
 		id = void 0;
-		isRunning(false);
+		pending(false);
 	};
 	const start = () => {
-		if (isRunning()) return;
-		isRunning(true);
+		if (pending()) return;
+		pending(true);
 		id = setTimeout(() => {
-			isRunning(false);
+			pending(false);
 			id = void 0;
 			callback();
 		}, getDelay());
@@ -31,7 +31,7 @@ function createTimeout(callback, delay, immediate = true) {
 	const cleanup = () => stop();
 	onCleanup(cleanup);
 	return {
-		isRunning,
+		pending,
 		start,
 		stop,
 		reset,

package/dist/utilities/timeout.test.mjs

@@ -14,7 +14,7 @@ describe("createTimeout", () => {
 		effectScope(() => {
 			t = createTimeout(cb, 500);
 		});
-		globalExpect(t.isRunning()).toBe(true);
+		globalExpect(t.pending()).toBe(true);
 	});
 	it("fires callback after delay", () => {
 		vi.useFakeTimers();
@@ -25,14 +25,14 @@ describe("createTimeout", () => {
 		vi.advanceTimersByTime(600);
 		globalExpect(cb).toHaveBeenCalledOnce();
 	});
-	it("isRunning becomes false after firing", () => {
+	it("pending becomes false after firing", () => {
 		vi.useFakeTimers();
 		let t;
 		effectScope(() => {
 			t = createTimeout(vi.fn(), 200);
 		});
 		vi.advanceTimersByTime(300);
-		globalExpect(t.isRunning()).toBe(false);
+		globalExpect(t.pending()).toBe(false);
 	});
 	it("stop() cancels the timeout", () => {
 		vi.useFakeTimers();

package/dist/utilities/window-focus.d.mts

@@ -0,0 +1,10 @@
+import { t as Computed } from "../index-DUshSQ_6.mjs";
+
+//#region src/utilities/window-focus.d.ts
+/**
+ * Singleton `Computed<boolean>` — `true` while the browser window has focus.
+ * Reacts to `focus` / `blur` window events.
+ */
+declare const windowFocused: Computed<boolean>;
+//#endregion
+export { windowFocused };

package/dist/utilities/window-focus.mjs

@@ -0,0 +1,16 @@
+import { _ as signal } from "../signals-BHmWX6ox.mjs";
+import { on } from "./event-listener.mjs";
+//#region src/utilities/window-focus.ts
+function createWindowFocused() {
+	const value = signal(typeof document !== "undefined" ? document.hasFocus() : true);
+	on(window, "focus", () => value(true));
+	on(window, "blur", () => value(false));
+	return value;
+}
+/**
+* Singleton `Computed<boolean>` — `true` while the browser window has focus.
+* Reacts to `focus` / `blur` window events.
+*/
+const windowFocused = createWindowFocused();
+//#endregion
+export { windowFocused };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "elements-kit",
   "type": "module",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "description": "A lightweight reactive UI library that transforms native HTMLElements into reactive components with signals. Ideal for framework-agnostic applications and web components.",
   "keywords": [
     "webcomponents",