elements-kit 0.0.9 → 0.0.11

package/dist/utilities/routing.mjs

@@ -0,0 +1,89 @@
+import { a as computed } from "../signals-DcgXhkU2.mjs";
+import { currentLocation } from "./location.mjs";
+//#region src/utilities/routing.ts
+const patchHistoryMethod = (method) => {
+	const original = history[method];
+	history[method] = function(data, unused, url) {
+		const result = original.apply(this, [
+			data,
+			unused,
+			url
+		]);
+		const event = new Event(method.toLowerCase());
+		event.state = data;
+		window.dispatchEvent(event);
+		return result;
+	};
+};
+function patchHistory() {
+	if (typeof window !== "undefined" && typeof history !== "undefined") {
+		patchHistoryMethod("pushState");
+		patchHistoryMethod("replaceState");
+	}
+}
+/**
+* Navigates to `url` via `history.pushState` (or `replaceState` when
+* `replace` is `true`).
+*
+* `history.pushState` / `replaceState` are patched once at module load so
+* all navigation — including third-party router calls — dispatches the
+* `pushstate` / `replacestate` events that `currentLocation` signals react to.
+*/
+function navigate(url, { replace = false, state = null } = {}) {
+	if (replace) history.replaceState(state, "", url);
+	else history.pushState(state, "", url);
+}
+/**
+* Returns `true` when a click event on an `<a>` element should be handled
+* client-side — same origin, primary button, no modifier keys, no download,
+* no `_blank` target. Walks up to the nearest anchor via `closest("a")`.
+*
+* Use alongside `navigate()` to intercept anchor clicks:
+*
+* ```ts
+* el.addEventListener("click", (e) => {
+*   if (isLocalNavigationEvent(e)) { e.preventDefault(); navigate(el.href); }
+* });
+* ```
+*/
+function isLocalNavigationEvent(e) {
+	if (e.button !== 0) return false;
+	if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return false;
+	const el = e.currentTarget?.closest("a") ?? e.target?.closest("a");
+	if (!el) return false;
+	if (el.hasAttribute("download")) return false;
+	if (el.getAttribute("target") === "_blank") return false;
+	if (new URL(el.href, location.href).origin !== location.origin) return false;
+	return true;
+}
+/**
+* Returns `Computed<boolean>` — `true` when the current URL matches `input`.
+* Uses `URLPattern.test()` — faster than `match` when you don't need
+* captured groups.
+*
+* Use object form: `{ pathname: "/users/:id" }`. Relative string patterns
+* require a base URL and will throw.
+*
+* Requires `urlpattern-polyfill` for Safari < 26 and Firefox < 142.
+*/
+function matches(input, options) {
+	const pattern = options ? new URLPattern(input, options) : new URLPattern(input);
+	return computed(() => pattern.test(currentLocation.href()));
+}
+/**
+* Returns `Computed<URLPatternResult | null>` — the full match result when
+* the current URL matches `input`, `null` when it does not.
+* Use when you need captured groups (params). For a boolean gate,
+* prefer `matches()` which is faster.
+*
+* Use object form: `{ pathname: "/users/:id" }`. Relative string patterns
+* require a base URL and will throw.
+*
+* Requires `urlpattern-polyfill` for Safari < 26 and Firefox < 142.
+*/
+function match(input, options) {
+	const pattern = options ? new URLPattern(input, options) : new URLPattern(input);
+	return computed(() => pattern.exec(currentLocation.href()));
+}
+//#endregion
+export { isLocalNavigationEvent, match, matches, navigate, patchHistory };

package/dist/utilities/routing.test.mjs

@@ -0,0 +1,128 @@
+import { i as beforeAll, n as vi, o as describe, r as afterEach, s as it, t as globalExpect } from "../test.BmQO5GaM-ANkhHvbr.mjs";
+import { isLocalNavigationEvent, match, matches, navigate, patchHistory } from "./routing.mjs";
+//#region src/utilities/routing.test.ts
+beforeAll(() => {
+	patchHistory();
+});
+afterEach(() => {
+	history.replaceState(null, "", "/");
+});
+describe("navigate", () => {
+	it("pushes a new history entry", () => {
+		navigate("/about");
+		globalExpect(location.pathname).toBe("/about");
+	});
+	it("replaces the current entry when replace is true", () => {
+		const before = history.length;
+		navigate("/replaced", { replace: true });
+		globalExpect(location.pathname).toBe("/replaced");
+		globalExpect(history.length).toBe(before);
+	});
+	it("dispatches pushstate event so currentLocation updates", () => {
+		const handler = vi.fn();
+		window.addEventListener("pushstate", handler);
+		navigate("/dispatched");
+		window.removeEventListener("pushstate", handler);
+		globalExpect(handler).toHaveBeenCalledOnce();
+	});
+	it("dispatches replacestate event on replace", () => {
+		const handler = vi.fn();
+		window.addEventListener("replacestate", handler);
+		navigate("/dispatched", { replace: true });
+		window.removeEventListener("replacestate", handler);
+		globalExpect(handler).toHaveBeenCalledOnce();
+	});
+});
+describe("isLocalNavigationEvent", () => {
+	function makeClick(el, init = {}) {
+		const e = new MouseEvent("click", {
+			bubbles: true,
+			cancelable: true,
+			...init
+		});
+		Object.defineProperty(e, "currentTarget", {
+			value: el,
+			configurable: true
+		});
+		return e;
+	}
+	it("returns true for a same-origin link", () => {
+		const el = document.createElement("a");
+		el.href = "/linked";
+		globalExpect(isLocalNavigationEvent(makeClick(el))).toBe(true);
+	});
+	it("returns false for an external link", () => {
+		const el = document.createElement("a");
+		el.href = "https://example.com/page";
+		globalExpect(isLocalNavigationEvent(makeClick(el))).toBe(false);
+	});
+	it("returns false when metaKey is held", () => {
+		const el = document.createElement("a");
+		el.href = "/about";
+		globalExpect(isLocalNavigationEvent(makeClick(el, { metaKey: true }))).toBe(false);
+	});
+	it("returns false when ctrlKey is held", () => {
+		const el = document.createElement("a");
+		el.href = "/about";
+		globalExpect(isLocalNavigationEvent(makeClick(el, { ctrlKey: true }))).toBe(false);
+	});
+	it("returns false for download links", () => {
+		const el = document.createElement("a");
+		el.href = "/file.pdf";
+		el.setAttribute("download", "");
+		globalExpect(isLocalNavigationEvent(makeClick(el))).toBe(false);
+	});
+	it("returns false for _blank links", () => {
+		const el = document.createElement("a");
+		el.href = "/page";
+		el.setAttribute("target", "_blank");
+		globalExpect(isLocalNavigationEvent(makeClick(el))).toBe(false);
+	});
+	it("returns false for non-primary button clicks", () => {
+		const el = document.createElement("a");
+		el.href = "/page";
+		globalExpect(isLocalNavigationEvent(makeClick(el, { button: 1 }))).toBe(false);
+	});
+});
+describe("matches", () => {
+	it("returns true when current URL matches", () => {
+		navigate("/users/42");
+		globalExpect(matches({ pathname: "/users/:id" })()).toBe(true);
+	});
+	it("returns false when current URL does not match", () => {
+		navigate("/other");
+		globalExpect(matches({ pathname: "/users/:id" })()).toBe(false);
+	});
+	it("updates reactively on navigation", () => {
+		const result = matches({ pathname: "/home" });
+		navigate("/other");
+		globalExpect(result()).toBe(false);
+		navigate("/home");
+		globalExpect(result()).toBe(true);
+	});
+});
+describe("match", () => {
+	it("returns null when current URL does not match", () => {
+		navigate("/other");
+		globalExpect(match({ pathname: "/users/:id" })()).toBeNull();
+	});
+	it("returns URLPatternResult with groups when matched", () => {
+		navigate("/users/42");
+		globalExpect(match({ pathname: "/users/:id" })()?.pathname.groups.id).toBe("42");
+	});
+	it("updates reactively on navigation", () => {
+		const result = match({ pathname: "/posts/:slug" });
+		navigate("/posts/hello");
+		globalExpect(result()?.pathname.groups.slug).toBe("hello");
+		navigate("/other");
+		globalExpect(result()).toBeNull();
+	});
+	it("extracts multiple params", () => {
+		navigate("/posts/2024/my-slug");
+		const result = match({ pathname: "/posts/:year/:slug" });
+		globalExpect(result()?.pathname.groups.year).toBe("2024");
+		globalExpect(result()?.pathname.groups.slug).toBe("my-slug");
+	});
+});
+//#endregion
+export {};

package/dist/utilities/search-params.d.mts

@@ -0,0 +1,13 @@
+import { t as Computed } from "../index-Cvdhuy6Y.mjs";
+
+//#region src/utilities/search-params.d.ts
+/**
+ * Returns a read-only `Computed<string | null>` bound to a single URL search
+ * parameter.
+ *
+ * Returns the raw string value, or `null` when absent.
+ * Reacts to `popstate` so back/forward navigation is reflected.
+ */
+declare function createSearchParam(key: string): Computed<string | null>;
+//#endregion
+export { createSearchParam };

package/dist/utilities/search-params.mjs

@@ -0,0 +1,23 @@
+import { fromEvent, sync } from "./event-driven.mjs";
+//#region src/utilities/search-params.ts
+/**
+* Returns a read-only `Computed<string | null>` bound to a single URL search
+* parameter.
+*
+* Returns the raw string value, or `null` when absent.
+* Reacts to `popstate` so back/forward navigation is reflected.
+*/
+function createSearchParam(key) {
+	const read = () => {
+		if (typeof location === "undefined") return null;
+		return new URLSearchParams(location.search).get(key);
+	};
+	const [s] = sync(fromEvent(window, [
+		"popstate",
+		"pushstate",
+		"replacestate"
+	]), read);
+	return s;
+}
+//#endregion
+export { createSearchParam };

package/dist/utilities/search-params.test.mjs

@@ -0,0 +1,35 @@
+import { s as effectScope } from "../signals-DcgXhkU2.mjs";
+import { o as describe, r as afterEach, s as it, t as globalExpect } from "../test.BmQO5GaM-ANkhHvbr.mjs";
+import { createSearchParam } from "./search-params.mjs";
+//#region src/utilities/search-params.test.ts
+afterEach(() => {
+	history.replaceState(null, "", location.pathname);
+});
+describe("createSearchParam", () => {
+	it("returns null when param is absent", () => {
+		let s;
+		effectScope(() => {
+			s = createSearchParam("q");
+		});
+		globalExpect(s()).toBeNull();
+	});
+	it("reads an existing param from the URL", () => {
+		history.replaceState(null, "", "?q=hello");
+		let s;
+		effectScope(() => {
+			s = createSearchParam("q");
+		});
+		globalExpect(s()).toBe("hello");
+	});
+	it("reacts to popstate events", () => {
+		let s;
+		effectScope(() => {
+			s = createSearchParam("q");
+		});
+		history.replaceState(null, "", "?q=changed");
+		window.dispatchEvent(new PopStateEvent("popstate"));
+		globalExpect(s()).toBe("changed");
+	});
+});
+//#endregion
+export {};

package/dist/utilities/storage.d.mts

@@ -0,0 +1,22 @@
+import { r as Signal } from "../index-Cvdhuy6Y.mjs";
+
+//#region src/utilities/storage.d.ts
+type StorageOptions<T> = {
+  /** Custom serialiser (default `JSON.stringify`). */serialise?: (value: T) => string; /** Custom deserialiser (default `JSON.parse`). */
+  deserialise?: (raw: string) => T;
+};
+/**
+ * Returns a `Signal` persisted to `localStorage`.
+ *
+ * Changes made in other tabs/windows are synchronised automatically via
+ * the `StorageEvent`.
+ */
+declare function createLocalStorage<T>(key: string, initialValue: T, options?: StorageOptions<T>): Signal<T>;
+/**
+ * Returns a `Signal` persisted to `sessionStorage`.
+ *
+ * Session storage is scoped to the current tab — no cross-tab sync.
+ */
+declare function createSessionStorage<T>(key: string, initialValue: T, options?: StorageOptions<T>): Signal<T>;
+//#endregion
+export { createLocalStorage, createSessionStorage };

package/dist/utilities/storage.mjs

@@ -0,0 +1,65 @@
+import { sync } from "./event-driven.mjs";
+//#region src/utilities/storage.ts
+function readOrDefault(storage, key, initialValue, deserialise) {
+	try {
+		const item = storage.getItem(key);
+		if (item !== null) return deserialise(item);
+	} catch {}
+	return initialValue;
+}
+/**
+* Returns a `Signal` persisted to `localStorage`.
+*
+* Changes made in other tabs/windows are synchronised automatically via
+* the `StorageEvent`.
+*/
+function createLocalStorage(key, initialValue, options) {
+	const serialise = options?.serialise ?? ((v) => JSON.stringify(v));
+	const deserialise = options?.deserialise ?? ((raw) => JSON.parse(raw));
+	const storage = localStorage;
+	let notify;
+	const subscribe = (cb) => {
+		notify = cb;
+		const handler = (e) => {
+			if (e.key === key && e.storageArea === storage) cb();
+		};
+		window.addEventListener("storage", handler);
+		return () => {
+			window.removeEventListener("storage", handler);
+			notify = void 0;
+		};
+	};
+	const [s] = sync(subscribe, () => readOrDefault(storage, key, initialValue, deserialise), (v) => {
+		try {
+			storage.setItem(key, serialise(v));
+		} catch {}
+		notify?.();
+	});
+	return s;
+}
+/**
+* Returns a `Signal` persisted to `sessionStorage`.
+*
+* Session storage is scoped to the current tab — no cross-tab sync.
+*/
+function createSessionStorage(key, initialValue, options) {
+	const serialise = options?.serialise ?? ((v) => JSON.stringify(v));
+	const deserialise = options?.deserialise ?? ((raw) => JSON.parse(raw));
+	const storage = sessionStorage;
+	let notify;
+	const subscribe = (cb) => {
+		notify = cb;
+		return () => {
+			notify = void 0;
+		};
+	};
+	const [s] = sync(subscribe, () => readOrDefault(storage, key, initialValue, deserialise), (v) => {
+		try {
+			storage.setItem(key, serialise(v));
+		} catch {}
+		notify?.();
+	});
+	return s;
+}
+//#endregion
+export { createLocalStorage, createSessionStorage };

package/dist/utilities/storage.test.mjs

@@ -0,0 +1,137 @@
+import { s as effectScope } from "../signals-DcgXhkU2.mjs";
+import { o as describe, r as afterEach, s as it, t as globalExpect } from "../test.BmQO5GaM-ANkhHvbr.mjs";
+import { createLocalStorage, createSessionStorage } from "./storage.mjs";
+//#region src/utilities/storage.test.ts
+describe("createLocalStorage", () => {
+	afterEach(() => {
+		localStorage.clear();
+	});
+	it("uses initialValue when storage is empty", () => {
+		let s;
+		effectScope(() => {
+			s = createLocalStorage("count", 0);
+		});
+		globalExpect(s()).toBe(0);
+	});
+	it("reads an existing value from localStorage", () => {
+		localStorage.setItem("count", "42");
+		let s;
+		effectScope(() => {
+			s = createLocalStorage("count", 0);
+		});
+		globalExpect(s()).toBe(42);
+	});
+	it("persists writes to localStorage", () => {
+		let s;
+		effectScope(() => {
+			s = createLocalStorage("key", "a");
+		});
+		s("b");
+		globalExpect(JSON.parse(localStorage.getItem("key"))).toBe("b");
+	});
+	it("persists complex values as JSON", () => {
+		let s;
+		effectScope(() => {
+			s = createLocalStorage("obj", { x: 1 });
+		});
+		s({ x: 99 });
+		globalExpect(JSON.parse(localStorage.getItem("obj"))).toEqual({ x: 99 });
+	});
+	it("falls back to initialValue on invalid JSON", () => {
+		localStorage.setItem("broken", "{not json}");
+		let s;
+		effectScope(() => {
+			s = createLocalStorage("broken", 7);
+		});
+		globalExpect(s()).toBe(7);
+	});
+	it("supports custom serialise / deserialise", () => {
+		let s;
+		effectScope(() => {
+			s = createLocalStorage("date", /* @__PURE__ */ new Date("2024-01-01"), {
+				serialise: (d) => d.toISOString(),
+				deserialise: (raw) => new Date(raw)
+			});
+		});
+		const d = /* @__PURE__ */ new Date("2025-06-15");
+		s(d);
+		globalExpect(localStorage.getItem("date")).toBe(d.toISOString());
+	});
+	it("reacts to storage events from other tabs", () => {
+		let s;
+		effectScope(() => {
+			s = createLocalStorage("sync-key", "init");
+		});
+		localStorage.setItem("sync-key", JSON.stringify("from-other-tab"));
+		window.dispatchEvent(new StorageEvent("storage", {
+			key: "sync-key",
+			newValue: JSON.stringify("from-other-tab"),
+			storageArea: localStorage
+		}));
+		globalExpect(s()).toBe("from-other-tab");
+	});
+	it("ignores storage events for different keys", () => {
+		let s;
+		effectScope(() => {
+			s = createLocalStorage("my-key", "init");
+		});
+		window.dispatchEvent(new StorageEvent("storage", {
+			key: "other-key",
+			newValue: JSON.stringify("nope"),
+			storageArea: localStorage
+		}));
+		globalExpect(s()).toBe("init");
+	});
+	it("resets to initialValue when key is removed", () => {
+		let s;
+		effectScope(() => {
+			s = createLocalStorage("rm-key", "default");
+		});
+		s("changed");
+		localStorage.removeItem("rm-key");
+		window.dispatchEvent(new StorageEvent("storage", {
+			key: "rm-key",
+			newValue: null,
+			storageArea: localStorage
+		}));
+		globalExpect(s()).toBe("default");
+	});
+});
+describe("createSessionStorage", () => {
+	afterEach(() => {
+		sessionStorage.clear();
+	});
+	it("uses initialValue when storage is empty", () => {
+		let s;
+		effectScope(() => {
+			s = createSessionStorage("count", 0);
+		});
+		globalExpect(s()).toBe(0);
+	});
+	it("reads an existing value from sessionStorage", () => {
+		sessionStorage.setItem("count", "42");
+		let s;
+		effectScope(() => {
+			s = createSessionStorage("count", 0);
+		});
+		globalExpect(s()).toBe(42);
+	});
+	it("persists writes to sessionStorage", () => {
+		let s;
+		effectScope(() => {
+			s = createSessionStorage("key", "a");
+		});
+		s("b");
+		globalExpect(JSON.parse(sessionStorage.getItem("key"))).toBe("b");
+	});
+	it("falls back to initialValue on invalid JSON", () => {
+		sessionStorage.setItem("broken", "{not json}");
+		let s;
+		effectScope(() => {
+			s = createSessionStorage("broken", 7);
+		});
+		globalExpect(s()).toBe(7);
+	});
+});
+//#endregion
+export {};

package/dist/{signals/lib → utilities}/throttled.d.mts

@@ -1,6 +1,6 @@
-import { t as Computed } from "../../index-BtqiEEfc.mjs";
+import { t as Computed } from "../index-Cvdhuy6Y.mjs";
 
-//#region src/signals/lib/throttled.d.ts
+//#region src/utilities/throttled.d.ts
 /**
  * Returns a `Computed` that mirrors `getter` but updates at most once per
  * `interval` milliseconds.  A trailing-edge update is scheduled so the final

package/dist/utilities/throttled.mjs

@@ -0,0 +1,36 @@
+import { o as effect, p as signal } from "../signals-DcgXhkU2.mjs";
+import { createTimeout } from "./timeout.mjs";
+//#region src/utilities/throttled.ts
+/**
+* Returns a `Computed` that mirrors `getter` but updates at most once per
+* `interval` milliseconds.  A trailing-edge update is scheduled so the final
+* value is never lost.
+*
+* The initial value is read synchronously.
+*/
+function createThrottled(getter, interval) {
+	const s = signal(getter());
+	let lastRun = -Infinity;
+	let firstRun = true;
+	let latest;
+	const { stop, reset } = createTimeout(() => {
+		lastRun = Date.now();
+		s(latest);
+	}, () => interval - (Date.now() - lastRun), false);
+	effect(() => {
+		latest = getter();
+		if (firstRun) {
+			firstRun = false;
+			return;
+		}
+		const elapsed = Date.now() - lastRun;
+		stop();
+		if (elapsed >= interval) {
+			lastRun = Date.now();
+			s(latest);
+		} else reset();
+	});
+	return s;
+}
+//#endregion
+export { createThrottled };

package/dist/{signals/lib → utilities}/throttled.test.mjs

@@ -1,7 +1,7 @@
-import { f as signal, o as effectScope } from "../../signals-CLAPw8kk.mjs";
-import { a as describe, i as beforeEach, n as vi, o as it, r as afterEach, t as globalExpect } from "../../test.BmQO5GaM-CR2qjV1t.mjs";
+import { p as signal, s as effectScope } from "../signals-DcgXhkU2.mjs";
+import { a as beforeEach, n as vi, o as describe, r as afterEach, s as it, t as globalExpect } from "../test.BmQO5GaM-ANkhHvbr.mjs";
 import { createThrottled } from "./throttled.mjs";
-//#region src/signals/lib/throttled.test.ts
+//#region src/utilities/throttled.test.ts
 beforeEach(() => {
 	vi.useFakeTimers();
 });

package/dist/{signals/lib → utilities}/timeout.d.mts

@@ -1,16 +1,17 @@
-import { t as Computed } from "../../index-BtqiEEfc.mjs";
+import { t as Computed } from "../index-Cvdhuy6Y.mjs";
 
-//#region src/signals/lib/timeout.d.ts
+//#region src/utilities/timeout.d.ts
 type TimeoutResult = {
-  isPending: Computed<boolean>;
+  isRunning: Computed<boolean>;
   start(): void;
   stop(): void;
   reset(): void;
 } & Disposable;
 /**
  * Reactive `setTimeout` wrapper with pause/resume/reset control.
- * The callback fires once after `delay` ms.  Starts running immediately.
+ * The callback fires once after `delay` ms.  Starts running immediately
+ * unless `immediate` is set to `false`.
  */
-declare function createTimeout(callback: () => void, delay: number): TimeoutResult;
+declare function createTimeout(callback: () => void, delay: number | (() => number), immediate?: boolean): TimeoutResult;
 //#endregion
 export { createTimeout };

package/dist/utilities/timeout.mjs

@@ -0,0 +1,42 @@
+import { f as onCleanup, p as signal } from "../signals-DcgXhkU2.mjs";
+//#region src/utilities/timeout.ts
+/**
+* Reactive `setTimeout` wrapper with pause/resume/reset control.
+* The callback fires once after `delay` ms.  Starts running immediately
+* unless `immediate` is set to `false`.
+*/
+function createTimeout(callback, delay, immediate = true) {
+	const isRunning = signal(false);
+	let id;
+	const getDelay = typeof delay === "function" ? delay : () => delay;
+	const stop = () => {
+		clearTimeout(id);
+		id = void 0;
+		isRunning(false);
+	};
+	const start = () => {
+		if (isRunning()) return;
+		isRunning(true);
+		id = setTimeout(() => {
+			isRunning(false);
+			id = void 0;
+			callback();
+		}, getDelay());
+	};
+	const reset = () => {
+		stop();
+		start();
+	};
+	if (immediate) start();
+	const cleanup = () => stop();
+	onCleanup(cleanup);
+	return {
+		isRunning,
+		start,
+		stop,
+		reset,
+		[Symbol.dispose]: cleanup
+	};
+}
+//#endregion
+export { createTimeout };