elements-kit 0.0.19 → 0.0.20

package/dist/utilities/retry.d.mts

@@ -4,6 +4,21 @@ 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.
+ *
+ * @example
+ * ```ts
+ * import { retry } from "elements-kit/utilities/retry";
+ *
+ * // Constant 500ms delay between retries
+ * const load = retry(() => fetch("/api").then(r => r.json()), 3, 500);
+ *
+ * // Exponential backoff
+ * const loadBackoff = retry(
+ *   () => fetch("/api").then(r => r.json()),
+ *   5,
+ *   (attempt) => 2 ** attempt * 100,
+ * );
+ * ```
  */
 declare function retry<T>(fn: () => Promise<T>, attempts: number, delay?: RetryDelay): () => Promise<T>;
 //#endregion

package/dist/utilities/retry.mjs

@@ -5,6 +5,21 @@ import "../signals/index.mjs";
 * 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.
+*
+* @example
+* ```ts
+* import { retry } from "elements-kit/utilities/retry";
+*
+* // Constant 500ms delay between retries
+* const load = retry(() => fetch("/api").then(r => r.json()), 3, 500);
+*
+* // Exponential backoff
+* const loadBackoff = retry(
+*   () => fetch("/api").then(r => r.json()),
+*   5,
+*   (attempt) => 2 ** attempt * 100,
+* );
+* ```
 */
 function retry(fn, attempts, delay) {
 	return async () => {

package/dist/utilities/routing.d.mts

@@ -1,6 +1,17 @@
-import { y as Computed } from "../infer-Dv5Wk-7E.mjs";
+import { y as Computed } from "../infer-DuFY-y2b.mjs";
 
 //#region src/utilities/routing.d.ts
+/**
+ * Monkey-patches `history.pushState` / `history.replaceState` to dispatch
+ * `pushstate` and `replacestate` events on `window`.
+ *
+ * Needed because the platform only fires `popstate` on back/forward
+ * navigation — `currentLocation` and anything else that reacts to
+ * programmatic navigation needs these synthetic events.
+ *
+ * Call once at app boot (or before any router-driven navigation). Safe to
+ * call outside a browser — it no-ops.
+ */
 declare function patchHistory(): void;
 type NavigateOptions = {
   replace?: boolean;

package/dist/utilities/routing.mjs

@@ -16,6 +16,17 @@ const patchHistoryMethod = (method) => {
 		return result;
 	};
 };
+/**
+* Monkey-patches `history.pushState` / `history.replaceState` to dispatch
+* `pushstate` and `replacestate` events on `window`.
+*
+* Needed because the platform only fires `popstate` on back/forward
+* navigation — `currentLocation` and anything else that reacts to
+* programmatic navigation needs these synthetic events.
+*
+* Call once at app boot (or before any router-driven navigation). Safe to
+* call outside a browser — it no-ops.
+*/
 function patchHistory() {
 	if (typeof window !== "undefined" && typeof history !== "undefined") {
 		patchHistoryMethod("pushState");

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

@@ -1,4 +1,4 @@
-import { y as Computed } from "../infer-Dv5Wk-7E.mjs";
+import { y as Computed } from "../infer-DuFY-y2b.mjs";
 
 //#region src/utilities/search-params.d.ts
 /**

package/dist/utilities/storage.d.mts

@@ -1,4 +1,4 @@
-import { x as Signal } from "../infer-Dv5Wk-7E.mjs";
+import { x as Signal } from "../infer-DuFY-y2b.mjs";
 
 //#region src/utilities/storage.d.ts
 type StorageOptions<T> = {
@@ -10,12 +10,29 @@ type StorageOptions<T> = {
  *
  * Changes made in other tabs/windows are synchronised automatically via
  * the `StorageEvent`.
+ *
+ * @example
+ * ```ts
+ * import { createLocalStorage } from "elements-kit/utilities/storage";
+ *
+ * const theme = createLocalStorage<"light" | "dark">("theme", "light");
+ * theme();         // read current
+ * theme("dark");   // write — persists and notifies
+ * ```
  */
 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.
+ *
+ * @example
+ * ```ts
+ * import { createSessionStorage } from "elements-kit/utilities/storage";
+ *
+ * const draft = createSessionStorage("draft", { title: "", body: "" });
+ * draft({ title: "hi", body: "…" });
+ * ```
  */
 declare function createSessionStorage<T>(key: string, initialValue: T, options?: StorageOptions<T>): Signal<T>;
 //#endregion

package/dist/utilities/storage.mjs

@@ -12,6 +12,15 @@ function readOrDefault(storage, key, initialValue, deserialise) {
 *
 * Changes made in other tabs/windows are synchronised automatically via
 * the `StorageEvent`.
+*
+* @example
+* ```ts
+* import { createLocalStorage } from "elements-kit/utilities/storage";
+*
+* const theme = createLocalStorage<"light" | "dark">("theme", "light");
+* theme();         // read current
+* theme("dark");   // write — persists and notifies
+* ```
 */
 function createLocalStorage(key, initialValue, options) {
 	const serialise = options?.serialise ?? ((v) => JSON.stringify(v));
@@ -41,6 +50,14 @@ function createLocalStorage(key, initialValue, options) {
 * Returns a `Signal` persisted to `sessionStorage`.
 *
 * Session storage is scoped to the current tab — no cross-tab sync.
+*
+* @example
+* ```ts
+* import { createSessionStorage } from "elements-kit/utilities/storage";
+*
+* const draft = createSessionStorage("draft", { title: "", body: "" });
+* draft({ title: "hi", body: "…" });
+* ```
 */
 function createSessionStorage(key, initialValue, options) {
 	const serialise = options?.serialise ?? ((v) => JSON.stringify(v));

package/dist/utilities/throttled.d.mts

@@ -1,4 +1,4 @@
-import { y as Computed } from "../infer-Dv5Wk-7E.mjs";
+import { y as Computed } from "../infer-DuFY-y2b.mjs";
 
 //#region src/utilities/throttled.d.ts
 /**
@@ -7,6 +7,17 @@ import { y as Computed } from "../infer-Dv5Wk-7E.mjs";
  * value is never lost.
  *
  * The initial value is read synchronously.
+ *
+ * @example
+ * ```ts
+ * import { signal } from "elements-kit/signals";
+ * import { createThrottled } from "elements-kit/utilities/throttled";
+ *
+ * const scrollY = signal(0);
+ * const sampled = createThrottled(scrollY, 100);
+ *
+ * effect(() => analytics.record(sampled()));
+ * ```
  */
 declare function createThrottled<T>(getter: () => T, interval: number): Computed<T>;
 //#endregion

package/dist/utilities/throttled.mjs

@@ -8,6 +8,17 @@ import { createTimeout } from "./timeout.mjs";
 * value is never lost.
 *
 * The initial value is read synchronously.
+*
+* @example
+* ```ts
+* import { signal } from "elements-kit/signals";
+* import { createThrottled } from "elements-kit/utilities/throttled";
+*
+* const scrollY = signal(0);
+* const sampled = createThrottled(scrollY, 100);
+*
+* effect(() => analytics.record(sampled()));
+* ```
 */
 function createThrottled(getter, interval) {
 	const s = signal(getter());

package/dist/utilities/timeout.d.mts

@@ -1,4 +1,4 @@
-import { y as Computed } from "../infer-Dv5Wk-7E.mjs";
+import { y as Computed } from "../infer-DuFY-y2b.mjs";
 
 //#region src/utilities/timeout.d.ts
 type TimeoutResult = {

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

@@ -1,4 +1,4 @@
-import { y as Computed } from "../infer-Dv5Wk-7E.mjs";
+import { y as Computed } from "../infer-DuFY-y2b.mjs";
 
 //#region src/utilities/window-focus.d.ts
 /**

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

@@ -1,4 +1,4 @@
-import { y as Computed } from "../infer-Dv5Wk-7E.mjs";
+import { y as Computed } from "../infer-DuFY-y2b.mjs";
 
 //#region src/utilities/window-size.d.ts
 type WindowSizeResult = {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "elements-kit",
   "type": "module",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "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",