elements-kit 0.0.8 → 0.0.9

package/dist/signals/lib/queue.test.mjs

@@ -0,0 +1,61 @@
+import { o as effectScope } from "../../signals-CLAPw8kk.mjs";
+import { a as describe, o as it, r as afterEach, t as globalExpect } from "../../test.BmQO5GaM-CR2qjV1t.mjs";
+import { createQueue } from "./queue.mjs";
+//#region src/signals/lib/queue.test.ts
+afterEach(() => {
+	document.body.innerHTML = "";
+});
+describe("createQueue", () => {
+	it("starts empty by default", () => {
+		let q;
+		effectScope(() => {
+			q = createQueue();
+		});
+		globalExpect(q.items()).toEqual([]);
+		globalExpect(q.size()).toBe(0);
+	});
+	it("add enqueues an item", () => {
+		let q;
+		effectScope(() => {
+			q = createQueue();
+		});
+		q.add(1);
+		q.add(2);
+		globalExpect(q.items()).toEqual([1, 2]);
+	});
+	it("remove dequeues the first item (FIFO)", () => {
+		let q;
+		effectScope(() => {
+			q = createQueue([
+				1,
+				2,
+				3
+			]);
+		});
+		globalExpect(q.remove()).toBe(1);
+		globalExpect(q.items()).toEqual([2, 3]);
+	});
+	it("peek returns the front without removing", () => {
+		let q;
+		effectScope(() => {
+			q = createQueue([10, 20]);
+		});
+		globalExpect(q.peek()).toBe(10);
+		globalExpect(q.size()).toBe(2);
+	});
+	it("clear empties the queue", () => {
+		let q;
+		effectScope(() => {
+			q = createQueue([
+				1,
+				2,
+				3
+			]);
+		});
+		q.clear();
+		globalExpect(q.items()).toEqual([]);
+		globalExpect(q.size()).toBe(0);
+	});
+});
+//#endregion
+export {};

package/dist/signals/lib/raf.d.mts

@@ -0,0 +1,17 @@
+import { t as Computed } from "../../index-BtqiEEfc.mjs";
+
+//#region src/signals/lib/raf.d.ts
+type RafResult = {
+  isRunning: Computed<boolean>;
+  start(): void;
+  stop(): void;
+} & Disposable;
+/**
+ * Looping `requestAnimationFrame` wrapper with start/stop control.
+ *
+ * The callback receives the `DOMHighResTimeStamp` elapsed since page load.
+ * Starts running immediately on creation.
+ */
+declare function createRaf(callback: (time: number) => void): RafResult;
+//#endregion
+export { createRaf };

package/dist/signals/lib/raf.mjs

@@ -0,0 +1,38 @@
+import { d as onCleanup, f as signal } from "../../signals-CLAPw8kk.mjs";
+//#region src/signals/lib/raf.ts
+/**
+* Looping `requestAnimationFrame` wrapper with start/stop control.
+*
+* The callback receives the `DOMHighResTimeStamp` elapsed since page load.
+* Starts running immediately on creation.
+*/
+function createRaf(callback) {
+	const isRunning = signal(false);
+	let rafId;
+	const loop = (time) => {
+		callback(time);
+		if (isRunning()) rafId = requestAnimationFrame(loop);
+	};
+	const start = () => {
+		if (isRunning()) return;
+		isRunning(true);
+		rafId = requestAnimationFrame(loop);
+	};
+	const stop = () => {
+		isRunning(false);
+		if (rafId !== void 0) {
+			cancelAnimationFrame(rafId);
+			rafId = void 0;
+		}
+	};
+	start();
+	const cleanup = () => stop();
+	onCleanup(cleanup);
+	return Object.assign({
+		isRunning,
+		start,
+		stop
+	}, { [Symbol.dispose]: cleanup });
+}
+//#endregion
+export { createRaf };

package/dist/signals/lib/raf.test.d.mts

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

package/dist/signals/lib/raf.test.mjs

@@ -0,0 +1,58 @@
+import { o as effectScope } from "../../signals-CLAPw8kk.mjs";
+import { a as describe, n as vi, o as it, r as afterEach, t as globalExpect } from "../../test.BmQO5GaM-CR2qjV1t.mjs";
+import { createRaf } from "./raf.mjs";
+//#region src/signals/lib/raf.test.ts
+afterEach(() => {
+	document.body.innerHTML = "";
+	vi.unstubAllGlobals();
+});
+describe("createRaf", () => {
+	it("starts running immediately", () => {
+		vi.stubGlobal("requestAnimationFrame", vi.fn().mockReturnValue(1));
+		vi.stubGlobal("cancelAnimationFrame", vi.fn());
+		let r;
+		effectScope(() => {
+			r = createRaf(vi.fn());
+		});
+		globalExpect(r.isRunning()).toBe(true);
+	});
+	it("calls the callback via RAF", () => {
+		let raf;
+		vi.stubGlobal("requestAnimationFrame", (cb) => {
+			raf = cb;
+			return 1;
+		});
+		vi.stubGlobal("cancelAnimationFrame", vi.fn());
+		const cb = vi.fn();
+		effectScope(() => {
+			createRaf(cb);
+		});
+		raf?.(16);
+		globalExpect(cb).toHaveBeenCalledWith(16);
+	});
+	it("stop() halts the loop", () => {
+		vi.stubGlobal("requestAnimationFrame", vi.fn().mockReturnValue(1));
+		const cancel = vi.fn();
+		vi.stubGlobal("cancelAnimationFrame", cancel);
+		let r;
+		effectScope(() => {
+			r = createRaf(vi.fn());
+		});
+		r.stop();
+		globalExpect(r.isRunning()).toBe(false);
+		globalExpect(cancel).toHaveBeenCalled();
+	});
+	it("Symbol.dispose stops the loop", () => {
+		const cancel = vi.fn();
+		vi.stubGlobal("requestAnimationFrame", vi.fn().mockReturnValue(1));
+		vi.stubGlobal("cancelAnimationFrame", cancel);
+		let r;
+		effectScope(() => {
+			r = createRaf(vi.fn());
+		});
+		r[Symbol.dispose]();
+		globalExpect(cancel).toHaveBeenCalled();
+	});
+});
+//#endregion
+export {};

package/dist/signals/lib/react.d.mts

@@ -1,4 +1,4 @@
-import { t as Computed } from "../../index-BGKVkZ6y.mjs";
+import { t as Computed } from "../../index-BtqiEEfc.mjs";
 
 //#region src/signals/lib/react.d.ts
 /**

package/dist/signals/lib/resize-observer.d.mts

@@ -0,0 +1,8 @@
+//#region src/signals/lib/resize-observer.d.ts
+/**
+ * Raw `ResizeObserver` wrapper with automatic cleanup.
+ * Use `createElementSize` / `createElementRect` for the common cases.
+ */
+declare function createResizeObserver(target: Element | (() => Element | null), callback: ResizeObserverCallback): Disposable;
+//#endregion
+export { createResizeObserver };

package/dist/signals/lib/resize-observer.mjs

@@ -0,0 +1,16 @@
+import { d as onCleanup } from "../../signals-CLAPw8kk.mjs";
+//#region src/signals/lib/resize-observer.ts
+/**
+* Raw `ResizeObserver` wrapper with automatic cleanup.
+* Use `createElementSize` / `createElementRect` for the common cases.
+*/
+function createResizeObserver(target, callback) {
+	const observer = new ResizeObserver(callback);
+	const el = typeof target === "function" ? target() : target;
+	if (el) observer.observe(el);
+	const cleanup = () => observer.disconnect();
+	onCleanup(cleanup);
+	return { [Symbol.dispose]: cleanup };
+}
+//#endregion
+export { createResizeObserver };

package/dist/signals/lib/resize-observer.test.d.mts

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

package/dist/signals/lib/resize-observer.test.mjs

@@ -0,0 +1,44 @@
+import { o as effectScope } from "../../signals-CLAPw8kk.mjs";
+import { a as describe, n as vi, o as it, r as afterEach, t as globalExpect } from "../../test.BmQO5GaM-CR2qjV1t.mjs";
+import { createResizeObserver } from "./resize-observer.mjs";
+//#region src/signals/lib/resize-observer.test.ts
+afterEach(() => {
+	document.body.innerHTML = "";
+	vi.unstubAllGlobals();
+});
+describe("createResizeObserver", () => {
+	it("observes a target element", () => {
+		const target = document.createElement("div");
+		document.body.appendChild(target);
+		const observe = vi.fn();
+		vi.stubGlobal("ResizeObserver", function MockRO() {
+			return {
+				observe,
+				disconnect: vi.fn()
+			};
+		});
+		effectScope(() => {
+			createResizeObserver(target, vi.fn());
+		});
+		globalExpect(observe).toHaveBeenCalledWith(target);
+	});
+	it("disconnects on Symbol.dispose", () => {
+		const target = document.createElement("div");
+		document.body.appendChild(target);
+		const disconnect = vi.fn();
+		vi.stubGlobal("ResizeObserver", function MockRO() {
+			return {
+				observe: vi.fn(),
+				disconnect
+			};
+		});
+		let ro;
+		effectScope(() => {
+			ro = createResizeObserver(target, vi.fn());
+		});
+		ro[Symbol.dispose]();
+		globalExpect(disconnect).toHaveBeenCalledOnce();
+	});
+});
+//#endregion
+export {};

package/dist/signals/lib/resource.d.mts

@@ -0,0 +1,23 @@
+import { t as Computed } from "../../index-BtqiEEfc.mjs";
+
+//#region src/signals/lib/resource.d.ts
+type ResourceResult<T> = {
+  data: Computed<T | undefined>;
+  loading: Computed<boolean>;
+  error: Computed<unknown>;
+  refetch(): void;
+};
+/**
+ * Runs an async `fetcher` and exposes `data`, `loading`, and `error` as
+ * reactive computeds.  An `AbortController` is created for each fetch; the
+ * previous request is cancelled whenever `refetch()` is called or the source
+ * reactive dependencies change.
+ *
+ * @param source - Reactive getter whose dependencies trigger a refetch.
+ * @param fetcher - Receives the resolved source value and an `AbortSignal`.
+ */
+declare function createResource<S, T>(source: () => S, fetcher: (source: S, signal: AbortSignal) => Promise<T>, options?: {
+  initialValue?: T;
+}): ResourceResult<T>;
+//#endregion
+export { createResource };

package/dist/signals/lib/resource.mjs

@@ -0,0 +1,43 @@
+import { a as effect, d as onCleanup, f as signal } from "../../signals-CLAPw8kk.mjs";
+//#region src/signals/lib/resource.ts
+/**
+* Runs an async `fetcher` and exposes `data`, `loading`, and `error` as
+* reactive computeds.  An `AbortController` is created for each fetch; the
+* previous request is cancelled whenever `refetch()` is called or the source
+* reactive dependencies change.
+*
+* @param source - Reactive getter whose dependencies trigger a refetch.
+* @param fetcher - Receives the resolved source value and an `AbortSignal`.
+*/
+function createResource(source, fetcher, options) {
+	const data = signal(options?.initialValue);
+	const loading = signal(false);
+	const error = signal(void 0);
+	const tick = signal(0);
+	effect(() => {
+		tick();
+		const src = source();
+		const controller = new AbortController();
+		loading(true);
+		error(void 0);
+		fetcher(src, controller.signal).then((result) => {
+			data(result);
+			loading(false);
+		}, (err) => {
+			if (err.name !== "AbortError") {
+				error(err);
+				loading(false);
+			}
+		});
+		onCleanup(() => controller.abort());
+	});
+	const refetch = () => tick(tick() + 1);
+	return {
+		data,
+		loading,
+		error,
+		refetch
+	};
+}
+//#endregion
+export { createResource };

package/dist/signals/lib/resource.test.d.mts

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

package/dist/signals/lib/resource.test.mjs

@@ -0,0 +1,56 @@
+import { f as signal, o as effectScope } from "../../signals-CLAPw8kk.mjs";
+import { a as describe, n as vi, o as it, r as afterEach, t as globalExpect } from "../../test.BmQO5GaM-CR2qjV1t.mjs";
+import { createResource } from "./resource.mjs";
+//#region src/signals/lib/resource.test.ts
+afterEach(() => {
+	document.body.innerHTML = "";
+	vi.useRealTimers();
+});
+describe("createResource", () => {
+	it("starts loading", () => {
+		const src = signal("url");
+		let r;
+		effectScope(() => {
+			r = createResource(() => src(), async (_s, _signal) => "data");
+		});
+		globalExpect(r.loading()).toBe(true);
+		globalExpect(r.data()).toBeUndefined();
+	});
+	it("resolves data and sets loading false", async () => {
+		const src = signal("url");
+		let r;
+		effectScope(() => {
+			r = createResource(() => src(), (_s, _signal) => Promise.resolve("hello"));
+		});
+		await new Promise((res) => setTimeout(res, 0));
+		globalExpect(r.data()).toBe("hello");
+		globalExpect(r.loading()).toBe(false);
+	});
+	it("captures errors", async () => {
+		const src = signal("url");
+		let r;
+		effectScope(() => {
+			r = createResource(() => src(), (_s, _signal) => Promise.reject(/* @__PURE__ */ new Error("fail")));
+		});
+		await new Promise((res) => setTimeout(res, 0));
+		globalExpect(r.error()).toBeInstanceOf(Error);
+		globalExpect(r.loading()).toBe(false);
+	});
+	it("refetch re-runs the fetcher", async () => {
+		const src = signal("url");
+		let callCount = 0;
+		let r;
+		effectScope(() => {
+			r = createResource(() => src(), async () => {
+				callCount++;
+				return "data";
+			});
+		});
+		await new Promise((res) => setTimeout(res, 0));
+		r.refetch();
+		await new Promise((res) => setTimeout(res, 0));
+		globalExpect(callCount).toBe(2);
+	});
+});
+//#endregion
+export {};

package/dist/signals/lib/scroll-state.d.mts

@@ -0,0 +1,19 @@
+import { t as Computed } from "../../index-BtqiEEfc.mjs";
+
+//#region src/signals/lib/scroll-state.d.ts
+type ScrollDirection = "left" | "right" | "none";
+type VerticalDirection = "up" | "down" | "none";
+type ScrollStateResult = {
+  x: Computed<number>;
+  y: Computed<number>;
+  directionX: Computed<ScrollDirection>;
+  directionY: Computed<VerticalDirection>;
+} & Disposable;
+/**
+ * Tracks the scroll position and scroll direction of `target` (defaults to
+ * `window`).  Returns reactive computeds for `x`, `y`, `directionX`, and
+ * `directionY`.
+ */
+declare function createScrollState(target?: Element | Window | (() => Element | null)): ScrollStateResult;
+//#endregion
+export { createScrollState };

package/dist/signals/lib/scroll-state.mjs

@@ -0,0 +1,46 @@
+import { f as signal } from "../../signals-CLAPw8kk.mjs";
+import { createEventListener } from "./event-listener.mjs";
+//#region src/signals/lib/scroll-state.ts
+function getScrollXY(target) {
+	if (target instanceof Window) return {
+		x: target.scrollX,
+		y: target.scrollY
+	};
+	return {
+		x: target.scrollLeft,
+		y: target.scrollTop
+	};
+}
+/**
+* Tracks the scroll position and scroll direction of `target` (defaults to
+* `window`).  Returns reactive computeds for `x`, `y`, `directionX`, and
+* `directionY`.
+*/
+function createScrollState(target) {
+	const resolved = target === void 0 ? window : typeof target === "function" ? target() ?? window : target;
+	const initial = getScrollXY(resolved);
+	const x = signal(initial.x);
+	const y = signal(initial.y);
+	const directionX = signal("none");
+	const directionY = signal("none");
+	let prevX = initial.x;
+	let prevY = initial.y;
+	const handler = () => {
+		const pos = getScrollXY(resolved);
+		directionX(pos.x > prevX ? "right" : pos.x < prevX ? "left" : "none");
+		directionY(pos.y > prevY ? "down" : pos.y < prevY ? "up" : "none");
+		prevX = pos.x;
+		prevY = pos.y;
+		x(pos.x);
+		y(pos.y);
+	};
+	const cleanup = createEventListener(resolved, "scroll", handler);
+	return Object.assign({
+		x,
+		y,
+		directionX,
+		directionY
+	}, { [Symbol.dispose]: cleanup });
+}
+//#endregion
+export { createScrollState };

package/dist/signals/lib/scroll-state.test.d.mts

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

package/dist/signals/lib/scroll-state.test.mjs

@@ -0,0 +1,94 @@
+import { o as effectScope } from "../../signals-CLAPw8kk.mjs";
+import { a as describe, o as it, r as afterEach, t as globalExpect } from "../../test.BmQO5GaM-CR2qjV1t.mjs";
+import { createScrollState } from "./scroll-state.mjs";
+//#region src/signals/lib/scroll-state.test.ts
+afterEach(() => {
+	document.body.innerHTML = "";
+});
+describe("createScrollState", () => {
+	it("starts at (0, 0) for a scrollable element", () => {
+		const el = document.createElement("div");
+		document.body.appendChild(el);
+		let state;
+		effectScope(() => {
+			state = createScrollState(el);
+		});
+		globalExpect(state.x()).toBe(0);
+		globalExpect(state.y()).toBe(0);
+		globalExpect(state.directionX()).toBe("none");
+		globalExpect(state.directionY()).toBe("none");
+	});
+	it("updates x/y and direction on scroll", () => {
+		const el = document.createElement("div");
+		Object.defineProperty(el, "scrollLeft", {
+			value: 0,
+			writable: true
+		});
+		Object.defineProperty(el, "scrollTop", {
+			value: 0,
+			writable: true
+		});
+		document.body.appendChild(el);
+		let state;
+		effectScope(() => {
+			state = createScrollState(el);
+		});
+		Object.defineProperty(el, "scrollLeft", {
+			value: 50,
+			writable: true
+		});
+		Object.defineProperty(el, "scrollTop", {
+			value: 100,
+			writable: true
+		});
+		el.dispatchEvent(new Event("scroll"));
+		globalExpect(state.x()).toBe(50);
+		globalExpect(state.y()).toBe(100);
+		globalExpect(state.directionX()).toBe("right");
+		globalExpect(state.directionY()).toBe("down");
+	});
+	it("reports 'left' and 'up' when scrolling backwards", () => {
+		const el = document.createElement("div");
+		Object.defineProperty(el, "scrollLeft", {
+			value: 100,
+			writable: true
+		});
+		Object.defineProperty(el, "scrollTop", {
+			value: 200,
+			writable: true
+		});
+		document.body.appendChild(el);
+		let state;
+		effectScope(() => {
+			state = createScrollState(el);
+		});
+		Object.defineProperty(el, "scrollLeft", {
+			value: 50,
+			writable: true
+		});
+		Object.defineProperty(el, "scrollTop", {
+			value: 80,
+			writable: true
+		});
+		el.dispatchEvent(new Event("scroll"));
+		globalExpect(state.directionX()).toBe("left");
+		globalExpect(state.directionY()).toBe("up");
+	});
+	it("removes the scroll listener on Symbol.dispose", () => {
+		const el = document.createElement("div");
+		document.body.appendChild(el);
+		let state;
+		effectScope(() => {
+			state = createScrollState(el);
+		});
+		state[Symbol.dispose]();
+		Object.defineProperty(el, "scrollLeft", {
+			value: 99,
+			writable: true
+		});
+		el.dispatchEvent(new Event("scroll"));
+		globalExpect(state.x()).toBe(0);
+	});
+});
+//#endregion
+export {};

package/dist/signals/lib/scrolling.d.mts

@@ -0,0 +1,12 @@
+import { t as Computed } from "../../index-BtqiEEfc.mjs";
+
+//#region src/signals/lib/scrolling.d.ts
+/**
+ * Returns a `Computed<boolean>` that is `true` while the user is actively
+ * scrolling `target` (defaults to `window`).
+ *
+ * Sets to `false` after `delay` ms of no scroll events (default: 150 ms).
+ */
+declare function createScrolling(target?: Element | Window, delay?: number): Computed<boolean> & Disposable;
+//#endregion
+export { createScrolling };

package/dist/signals/lib/scrolling.mjs

@@ -0,0 +1,26 @@
+import { d as onCleanup, f as signal } from "../../signals-CLAPw8kk.mjs";
+import { createEventListener } from "./event-listener.mjs";
+//#region src/signals/lib/scrolling.ts
+/**
+* Returns a `Computed<boolean>` that is `true` while the user is actively
+* scrolling `target` (defaults to `window`).
+*
+* Sets to `false` after `delay` ms of no scroll events (default: 150 ms).
+*/
+function createScrolling(target = window, delay = 150) {
+	const scrolling = signal(false);
+	let timer;
+	const handler = () => {
+		scrolling(true);
+		clearTimeout(timer);
+		timer = setTimeout(() => scrolling(false), delay);
+	};
+	const removeListener = createEventListener(target, "scroll", handler, { passive: true });
+	onCleanup(() => clearTimeout(timer));
+	return Object.assign(scrolling, { [Symbol.dispose]: () => {
+		clearTimeout(timer);
+		removeListener();
+	} });
+}
+//#endregion
+export { createScrolling };

package/dist/signals/lib/scrolling.test.d.mts

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

package/dist/signals/lib/scrolling.test.mjs

@@ -0,0 +1,57 @@
+import { o as effectScope } from "../../signals-CLAPw8kk.mjs";
+import { a as describe, n as vi, o as it, r as afterEach, t as globalExpect } from "../../test.BmQO5GaM-CR2qjV1t.mjs";
+import { createScrolling } from "./scrolling.mjs";
+//#region src/signals/lib/scrolling.test.ts
+afterEach(() => {
+	document.body.innerHTML = "";
+	vi.useRealTimers();
+});
+describe("createScrolling", () => {
+	it("starts as false", () => {
+		vi.useFakeTimers();
+		const el = document.createElement("div");
+		document.body.appendChild(el);
+		let scrolling;
+		effectScope(() => {
+			scrolling = createScrolling(el);
+		});
+		globalExpect(scrolling()).toBe(false);
+	});
+	it("becomes true on scroll event", () => {
+		vi.useFakeTimers();
+		const el = document.createElement("div");
+		document.body.appendChild(el);
+		let scrolling;
+		effectScope(() => {
+			scrolling = createScrolling(el);
+		});
+		el.dispatchEvent(new Event("scroll"));
+		globalExpect(scrolling()).toBe(true);
+	});
+	it("returns to false after delay", () => {
+		vi.useFakeTimers();
+		const el = document.createElement("div");
+		document.body.appendChild(el);
+		let scrolling;
+		effectScope(() => {
+			scrolling = createScrolling(el, 150);
+		});
+		el.dispatchEvent(new Event("scroll"));
+		vi.advanceTimersByTime(200);
+		globalExpect(scrolling()).toBe(false);
+	});
+	it("stops reacting after Symbol.dispose", () => {
+		vi.useFakeTimers();
+		const el = document.createElement("div");
+		document.body.appendChild(el);
+		let scrolling;
+		effectScope(() => {
+			scrolling = createScrolling(el);
+		});
+		scrolling[Symbol.dispose]();
+		el.dispatchEvent(new Event("scroll"));
+		globalExpect(scrolling()).toBe(false);
+	});
+});
+//#endregion
+export {};

package/dist/signals/lib/search-params.d.mts

@@ -0,0 +1,16 @@
+import { t as Computed } from "../../index-BtqiEEfc.mjs";
+
+//#region src/signals/lib/search-params.d.ts
+type SearchParamsResult = {
+  params: Computed<URLSearchParams>;
+  get(key: string): string | null;
+  set(key: string, value: string): void;
+  delete(key: string): void;
+} & Disposable;
+/**
+ * Returns reactive access to the URL's search params.  Writing via `set` /
+ * `delete` updates both `location.search` and the reactive signal.
+ */
+declare function createSearchParams(): SearchParamsResult;
+//#endregion
+export { createSearchParams };