elements-kit 0.0.13 → 0.0.15

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/{element-C_4VbkvQ.mjs → element-ChF24-2z.mjs}

@@ -216,13 +216,8 @@ function setEvent(el, key, handler) {
 	return () => el.removeEventListener(event, handler);
 }
 //#endregion
-//#region src/jsx-runtime/ref.ts
-const $ref = Symbol("ref");
-//#endregion
 //#region src/jsx-runtime/element.ts
-function createElement(type, rawProps = {}) {
-	const ref = rawProps[$ref];
-	const props = Object.fromEntries(Object.entries(rawProps));
+function createElement(type, { ref, ...props } = {}) {
 	if (typeof type === "function" && !type.prototype?.render) return createFunctionElement(type, props, ref);
 	return createNodeElement(type, props, ref);
 }

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { n as disposeElement } from "./element-C_4VbkvQ.mjs";
+import { n as disposeElement } from "./element-ChF24-2z.mjs";
 import { _ as signal, g as onCleanup, u as effect, v as trigger, y as untracked } from "./signals-BHmWX6ox.mjs";
 //#region src/jsx-runtime/for.ts
 /**

package/dist/jsx-runtime/index.d.mts

@@ -15,10 +15,12 @@ type Child = PrimitiveNodeType | AnyFn | Child[];
 type AnyFn = (...args: any[]) => any;
 //#endregion
 //#region src/jsx-runtime/element.d.ts
-declare function createElement(type: string | Element | DocumentFragment | ComponentClass | ComponentFn, rawProps?: Record<string | symbol, unknown>): Element | DocumentFragment | null;
-//#endregion
-//#region src/jsx-runtime/ref.d.ts
-declare const $ref: unique symbol;
+declare function createElement(type: string | Element | DocumentFragment | ComponentClass | ComponentFn, {
+  ref,
+  ...props
+}?: Record<string | symbol, unknown> & {
+  ref?: (el: Element) => void;
+}): Element | DocumentFragment | null;
 //#endregion
 //#region src/jsx-runtime/fragment.d.ts
 /**
@@ -59,7 +61,7 @@ type SlotProps<K extends string> = { [P in K as `slot:${P}`]?: Child };
 type Attrs<K extends keyof JSX.IntrinsicElements> = JSX.IntrinsicElements[K];
 /** Extra props injected into every intrinsic element beyond dom-expressions defaults. */
 type OurProps = {
-  [$ref]?: (el: Element) => void;
+  ref?: (el: Element) => void;
   [slot: `slot:${string}`]: Child;
   [cls: `class:${string}`]: FunctionMaybe<boolean>;
   [sty: `style:${string}`]: FunctionMaybe<string | null>;

package/dist/jsx-runtime/index.mjs

@@ -1,4 +1,4 @@
-import { t as createElement } from "../element-C_4VbkvQ.mjs";
+import { t as createElement } from "../element-ChF24-2z.mjs";
 import { g as onCleanup } from "../signals-BHmWX6ox.mjs";
 //#region src/jsx-runtime/fragment.ts
 /**

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

@@ -1,5 +1,6 @@
 import { d as effectScope } from "../signals-BHmWX6ox.mjs";
 import { n as vi, o as describe, r as afterEach, s as it, t as globalExpect } from "../test.BmQO5GaM-ANkhHvbr.mjs";
+import { async } from "./async.mjs";
 import { createInterval } from "./interval.mjs";
 //#region src/utilities/interval.test.ts
 afterEach(() => {
@@ -26,7 +27,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 +64,50 @@ 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);
+	});
+	it("composes with async() — reruns on each tick", async () => {
+		vi.useFakeTimers();
+		const asyncOp = async;
+		let runCount = 0;
+		const timer = createInterval(100);
+		const op = asyncOp(() => {
+			timer.timestamp();
+			runCount++;
+			return Promise.resolve(runCount);
+		}).start();
+		await vi.advanceTimersByTimeAsync(350);
+		globalExpect(runCount).toBeGreaterThan(1);
+		timer[Symbol.dispose]();
+		op.stop();
+	});
 });
 //#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 };