elements-kit 0.0.19 → 0.1.0

package/dist/{infer-Dv5Wk-7E.d.mts → infer-DuFY-y2b.d.mts}

@@ -1,6 +1,6 @@
-import { n as AttrChangeHandler, t as ATTRIBUTES } from "./attributes-aiRoArZz.mjs";
-import { t as CustomElementRegistry } from "./custom-elements-bVYOkHKt.mjs";
-import { a as PrimitiveNodeType, i as Slots, n as Slot, t as SLOTS } from "./slot-B5_VHB7E.mjs";
+import { n as AttrChangeHandler, t as ATTRIBUTES } from "./attributes-DILeh3-s.mjs";
+import { t as CustomElementRegistry } from "./custom-elements-D5_NMNyD.mjs";
+import { a as PrimitiveNodeType, i as Slots, n as Slot, t as SLOTS } from "./slot-D5iBUSAm.mjs";
 import { JSX } from "dom-expressions/src/jsx-h";
 
 //#region src/jsx-runtime/element.d.ts
@@ -233,9 +233,44 @@ declare function untracked<T>(fn: Computed<T>): T;
 declare function trigger<T = void>(fn: Computed<T>): void;
 //#endregion
 //#region src/signals/index.d.ts
+/**
+ * Type-guard: `true` when `value` is a reactive source (`signal` or `computed`),
+ * `false` when it is a plain value.
+ *
+ * Use this when you accept {@link MaybeReactive} and need to branch on whether
+ * the caller passed a live source or a static value.
+ *
+ * @example
+ * ```ts
+ * import { signal, isReactive } from "elements-kit/signals";
+ *
+ * const a: MaybeReactive<number> = 5;
+ * const b: MaybeReactive<number> = signal(0);
+ * const c: () => number = () => 5;
+ *
+ * isReactive(a); // false
+ * isReactive(b); // true
+ * isReactive(c); // false
+ * ```
+ */
 declare function isReactive<T>(value: MaybeReactive<T>): value is () => T;
+/** Writer half of a {@link Signal}: `sig(next)` assigns a new value. */
 type Updater<T> = (value: T) => void;
+/** Zero-arg getter that subscribes the current tracking scope on call. */
 type Computed<T> = () => T;
+/**
+ * A reactive read/write cell — callable as both a getter (no args) and a
+ * setter (one arg).
+ *
+ * @example
+ * ```ts
+ * import { signal } from "elements-kit/signals";
+ *
+ * const count: Signal<number> = signal(0);
+ * count();   // read → 0 (subscribes the active scope)
+ * count(5);  // write → notifies subscribers
+ * ```
+ */
 type Signal<T> = Updater<T> & Computed<T>;
 /**
  * A decorator that makes a class field reactive by automatically wrapping its value in a signal.
@@ -246,8 +281,7 @@ type Signal<T> = Updater<T> & Computed<T>;
  * @example
  * ```ts
  * class Counter {
- *   @reactive()
- *   count: number = 0;
+ *   \@reactive() count: number = 0;
  * }
  *
  * const counter = new Counter();
@@ -359,15 +393,26 @@ type SlotProps<K extends string> = { [P in K as `slot:${P}`]?: Child };
  * ```
  */
 type Attrs<K extends keyof JSX$1.IntrinsicElements> = JSX$1.IntrinsicElements[K];
-/** Extra props injected into every intrinsic element beyond dom-expressions defaults. */
-type OurProps = {
+/**
+ * Namespaced JSX props added by elements-kit on top of dom-expressions.
+ *
+ * - `ref` — callback invoked with the mounted element.
+ * - `slot:foo` — accepts any `Child`. Reactive children come for free because
+ *   `Child` already includes `AnyFn` (so `() => content()` and `signal` both
+ *   typecheck and are wired as reactive slots by `mountChild`).
+ * - `class:foo` / `style:foo` — `MaybeReactive<T>` (value or zero-arg getter),
+ *   because their value types (`boolean` / `string | null`) are primitives
+ *   that don't otherwise allow function form.
+ * - `prop:foo` — any value, direct property assignment, no reactive coupling.
+ */
+type JsxNamespaces = {
   ref?: (el: Element) => void;
-  [slot: `slot:${string}`]: Computed<Child>;
-  [cls: `class:${string}`]: Computed<boolean>;
-  [sty: `style:${string}`]: Computed<string | null>;
-  [prop: `prop:${string}`]: Computed<unknown>;
+  [slot: `slot:${string}`]: Child;
+  [cls: `class:${string}`]: MaybeReactive<boolean>;
+  [sty: `style:${string}`]: MaybeReactive<string | null>;
+  [prop: `prop:${string}`]: unknown;
 };
-type WithOurProps<T> = T & OurProps;
+type WithJsxNamespaces<T> = T & JsxNamespaces;
 declare namespace JSX$1 {
   export type Element = globalThis.Element | globalThis.DocumentFragment | null;
   export type ElementType = Child | Component;
@@ -378,9 +423,9 @@ declare namespace JSX$1 {
     ref?: (el: Element) => void;
   }
   export type LibraryManagedAttributes<C, P> = ResolveProps<C, P>;
-  type RegisteredElements = { [K in keyof CustomElementRegistry]: CustomElementRegistry[K] extends AnyElementCtor ? ElementProps<CustomElementRegistry[K]> : never };
-  export type IntrinsicElements = { [K in keyof JSX.IntrinsicElements]: WithOurProps<JSX.IntrinsicElements[K]> } & RegisteredElements & {
-    /** Unregistered custom elements (`x-foo`, `my-component`, …) — loose fallback. */[customElement: `${string}-${string}`]: WithOurProps<JSX.DOMAttributes<HTMLElement>> & Record<string, unknown>;
+  type RegisteredElements = { [K in keyof CustomElementRegistry]: CustomElementRegistry[K] extends AnyElementCtor ? MaybeReactiveProps<ElementProps<CustomElementRegistry[K]>> : never };
+  export type IntrinsicElements = { [K in keyof JSX.IntrinsicElements]: WithJsxNamespaces<JSX.IntrinsicElements[K]> } & RegisteredElements & {
+    /** Unregistered custom elements (`x-foo`, `my-component`, …) — loose fallback. */[customElement: `${string}-${string}`]: WithJsxNamespaces<JSX.DOMAttributes<HTMLElement>> & Record<string, unknown>;
   };
   export {};
 }
@@ -487,14 +532,14 @@ type AttrMap<C> = C extends {
   [ATTRIBUTES]: infer M;
 } ? M : {};
 type HandlerValue<H> = H extends AttrChangeHandler<any> ? string | null : H;
-type AttrsOf<C> = AttrMap<C> extends infer M ? M extends Record<string, unknown> ? { [K in Exclude<keyof M & string, PropKeysOf<C>>]?: MaybeReactive<HandlerValue<M[K]>> } : {} : {};
-type FlatPropsOf<C> = MaybeReactiveProps<InstancePropsOf<C>>;
+type AttrsOf<C> = AttrMap<C> extends infer M ? M extends Record<string, unknown> ? string extends keyof M ? {} : { [K in Exclude<keyof M & string, PropKeysOf<C>>]?: HandlerValue<M[K]> } : {} : {};
+type FlatPropsOf<C> = InstancePropsOf<C>;
 type PropNamespacedOf<C> = { [K in PropKeysOf<C> as `prop:${K}`]?: NonNullable<InstancePropsOf<C>[K]> };
 type EventMapOf<C> = C extends {
   events: infer E;
 } ? E : {};
 type Capitalize1<S extends string> = S extends `${infer H}${infer R}` ? `${Uppercase<H>}${R}` : S;
-type EventsOf<C> = EventMapOf<C> extends infer E ? E extends Record<string, Event> ? { [K in keyof E & string as `on:${K}`]?: MaybeReactive<(ev: E[K]) => void> } & { [K in keyof E & string as `on${Capitalize1<K>}`]?: MaybeReactive<(ev: E[K]) => void> } : {} : {};
+type EventsOf<C> = EventMapOf<C> extends infer E ? E extends Record<string, Event> ? { [K in keyof E & string as `on:${K}`]?: (ev: E[K]) => void } & { [K in keyof E & string as `on${Capitalize1<K>}`]?: (ev: E[K]) => void } : {} : {};
 type SlotKeys<I> = I extends {
   [SLOTS]: Slots<infer K>;
 } ? K : never;
@@ -506,12 +551,6 @@ type ChildrenOf<C> = C extends {
   children?: Child;
 };
 type BaseDOMAttrs = JSX.DOMAttributes<HTMLElement>;
-type Namespaces = {
-  ref?: (el: Element) => void;
-  [cls: `class:${string}`]: MaybeReactive<boolean>;
-  [sty: `style:${string}`]: MaybeReactive<string | null>;
-  [prop: `prop:${string}`]: unknown;
-};
 /**
  * Full JSX prop type for a custom-element class (extends `HTMLElement`).
  *
@@ -530,12 +569,12 @@ type Namespaces = {
  *
  * @example
  * ```ts
- * @attributes
+ * \@attributes
  * class XRange extends HTMLElement {
  *   static [ATTRIBUTES]: Attributes<XRange> = { min(v) { this.min = +v! } };
  *   declare static events: { commit: CustomEvent<number> };
  *   [SLOTS] = Slots.new(["label"] as const);
- *   @reactive() min = 0;
+ *   \@reactive() min = 0;
  * }
  *
  * type Props = ElementProps<typeof XRange>;
@@ -552,7 +591,7 @@ type Namespaces = {
  *
  * @see {@link Props} for class-components / function components (no attr/event/slot synthesis).
  */
-type ElementProps<C extends AnyElementCtor> = BaseDOMAttrs & AttrsOf<C> & FlatPropsOf<C> & PropNamespacedOf<C> & EventsOf<C> & SlotsOf<C> & ChildrenOf<C> & Namespaces;
+type ElementProps<C extends AnyElementCtor> = BaseDOMAttrs & AttrsOf<C> & FlatPropsOf<C> & PropNamespacedOf<C> & EventsOf<C> & SlotsOf<C> & ChildrenOf<C>;
 /**
  * Props of a class component that receives them via its constructor:
  * `class Comp { constructor(props: P) }`. Reads `ConstructorParameters[0]`.

package/dist/integrations/react.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/integrations/react.d.ts
 /**

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

@@ -1,2 +1,2 @@
-import { U as createElement, _ as SlotProps, a as RawProps, b as MaybeReactive, c as ResolveProps, d as ComponentClass, f as ComponentFn, g as JSX, h as Attrs, i as Props, l as Child, m as PropsTarget, n as ElementProps, o as ReactiveProps, p as ComponentInstance, r as MaybeReactiveProps, s as Require, t as ComponentProps, u as Component, v as Fragment } from "../infer-Dv5Wk-7E.mjs";
+import { U as createElement, _ as SlotProps, a as RawProps, b as MaybeReactive, c as ResolveProps, d as ComponentClass, f as ComponentFn, g as JSX, h as Attrs, i as Props, l as Child, m as PropsTarget, n as ElementProps, o as ReactiveProps, p as ComponentInstance, r as MaybeReactiveProps, s as Require, t as ComponentProps, u as Component, v as Fragment } from "../infer-DuFY-y2b.mjs";
 export { Attrs, Child, Component, ComponentClass, ComponentFn, ComponentInstance, ComponentProps, ElementProps, Fragment, JSX, MaybeReactive, MaybeReactiveProps, Props, PropsTarget, RawProps, ReactiveProps, Require, ResolveProps, SlotProps, createElement as h, createElement as jsx, createElement as jsxDEV, createElement as jsxs };

package/dist/jsx-runtime/index.mjs

@@ -1,4 +1,4 @@
-import { r as mountChild, t as createElement } from "../element-DxmInKJw.mjs";
+import { r as mountChild, t as createElement } from "../element-w1GCIMVp.mjs";
 //#region src/jsx-runtime/fragment.ts
 /**
 * Used by the JSX transform for `<>...</>` fragments.

package/dist/signals/index.d.mts

@@ -1,2 +1,2 @@
-import { A as SIGNAL, B as signal, C as isReactive, D as COMPUTED, E as resolveProps, F as isComputed, H as untracked, I as isEffect, L as isEffectScope, M as computed, N as effect, O as EFFECT, P as effectScope, R as isSignal, S as Updater, T as resolve, V as trigger, b as MaybeReactive, j as batch, k as EFFECT_SCOPE, w as reactive, x as Signal, y as Computed, z as onCleanup } from "../infer-Dv5Wk-7E.mjs";
+import { A as SIGNAL, B as signal, C as isReactive, D as COMPUTED, E as resolveProps, F as isComputed, H as untracked, I as isEffect, L as isEffectScope, M as computed, N as effect, O as EFFECT, P as effectScope, R as isSignal, S as Updater, T as resolve, V as trigger, b as MaybeReactive, j as batch, k as EFFECT_SCOPE, w as reactive, x as Signal, y as Computed, z as onCleanup } from "../infer-DuFY-y2b.mjs";
 export { COMPUTED, Computed, EFFECT, EFFECT_SCOPE, MaybeReactive, SIGNAL, Signal, Updater, batch, computed, effect, effectScope, isComputed, isEffect, isEffectScope, isReactive, isSignal, onCleanup, reactive, resolve, resolveProps, signal, trigger, untracked };

package/dist/signals/index.mjs

@@ -1,6 +1,26 @@
 import { a as batch, c as effectScope, d as isEffectScope, f as isSignal, g as untracked, h as trigger, i as SIGNAL, l as isComputed, m as signal, n as EFFECT, o as computed, p as onCleanup, r as EFFECT_SCOPE, s as effect, t as COMPUTED, u as isEffect } from "../lib-D6duEs38.mjs";
 import "../polyfill-B1lNNcum.mjs";
 //#region src/signals/index.ts
+/**
+* Type-guard: `true` when `value` is a reactive source (`signal` or `computed`),
+* `false` when it is a plain value.
+*
+* Use this when you accept {@link MaybeReactive} and need to branch on whether
+* the caller passed a live source or a static value.
+*
+* @example
+* ```ts
+* import { signal, isReactive } from "elements-kit/signals";
+*
+* const a: MaybeReactive<number> = 5;
+* const b: MaybeReactive<number> = signal(0);
+* const c: () => number = () => 5;
+*
+* isReactive(a); // false
+* isReactive(b); // true
+* isReactive(c); // false
+* ```
+*/
 function isReactive(value) {
 	return isSignal(value) || isComputed(value);
 }
@@ -13,8 +33,7 @@ function isReactive(value) {
 * @example
 * ```ts
 * class Counter {
-*   @reactive()
-*   count: number = 0;
+*   \@reactive() count: number = 0;
 * }
 *
 * const counter = new Counter();

package/dist/{slot-Kb61AcgW.mjs → slot-CKtUoy2X.mjs}

@@ -127,7 +127,6 @@ var Slot = class Slot {
 		});
 	}
 };
-/** A callable slot — invoke to render, or access `.set()` / `.isMounted()` / `.parent()` for management. */
 /**
 * Symbol key for attaching a `Slots` instance to a custom element instance.
 * This prevent collisions with Element properties and are not meant to be treated as JSX children.

package/dist/{slot-B5_VHB7E.d.mts → slot-D5iBUSAm.d.mts}

@@ -63,8 +63,15 @@ declare class Slot {
    */
   static new(): Slot & ((defaultContent?: PrimitiveNodeType) => DocumentFragment);
 }
+/**
+ * A callable slot returned by {@link Slot.new}.
+ *
+ * - Invoke it (`slot()`) to render the slot region as a `DocumentFragment`,
+ *   optionally with default content on first mount.
+ * - Call `.set()` to replace current content, `.clear()` to empty it, and
+ *   `.isMounted()` / `.parent()` to inspect mount state.
+ */
 type SlotInstance = ReturnType<typeof Slot.new>;
-/** A callable slot — invoke to render, or access `.set()` / `.isMounted()` / `.parent()` for management. */
 /**
  * Symbol key for attaching a `Slots` instance to a custom element instance.
  * This prevent collisions with Element properties and are not meant to be treated as JSX children.

package/dist/slot.d.mts

@@ -1,2 +1,2 @@
-import { i as Slots, n as Slot, r as SlotInstance, t as SLOTS } from "./slot-B5_VHB7E.mjs";
+import { i as Slots, n as Slot, r as SlotInstance, t as SLOTS } from "./slot-D5iBUSAm.mjs";
 export { SLOTS, Slot, SlotInstance, Slots };

package/dist/slot.mjs

@@ -1,2 +1,2 @@
-import { n as Slot, r as Slots, t as SLOTS } from "./slot-Kb61AcgW.mjs";
+import { n as Slot, r as Slots, t as SLOTS } from "./slot-CKtUoy2X.mjs";
 export { SLOTS, Slot, Slots };

package/dist/utilities/active-element.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/active-element.d.ts
 declare const activeElement: Computed<Element | null>;

package/dist/utilities/async.d.mts

@@ -1,8 +1,29 @@
-import { b as MaybeReactive } from "../infer-Dv5Wk-7E.mjs";
+import { b as MaybeReactive } from "../infer-DuFY-y2b.mjs";
 import { ComputedPromise } from "./promise.mjs";
 
 //#region src/utilities/async.d.ts
+/** Shape of the async function driven by {@link Async} / {@link async}. */
 type Fn<TInput, TOutput> = (input: TInput) => Promise<TOutput>;
+/**
+ * Reactive wrapper around an async function. Exposes the current run as
+ * reactive signals (`state`, `value`, `reason`, `result`, `pending`) and
+ * lets you `run`/`start`/`stop` the underlying task imperatively.
+ *
+ * Prefer the {@link async} factory — it returns an `Async` that is also
+ * callable as a signal (`op()` === `op.result`), which is what most call
+ * sites want. Use this class directly only when you need the object form.
+ *
+ * @example
+ * ```ts
+ * import { Async } from "elements-kit/utilities/async";
+ *
+ * const loader = new Async<string, User>(fetchUser);
+ * loader.run("alice");
+ * effect(() => {
+ *   if (loader.state === "fulfilled") console.log(loader.value);
+ * });
+ * ```
+ */
 declare class Async<TInput = undefined, TOutput = unknown> {
   #private;
   get fn(): Fn<TInput, TOutput>;
@@ -32,6 +53,23 @@ declare class Async<TInput = undefined, TOutput = unknown> {
    */
   start(...args: TInput extends undefined ? [] : [input: TInput]): this;
 }
+/**
+ * Create an {@link Async} that is also callable as a signal: invoking it
+ * (with no args) reads the current `result`, so it drops into any reactive
+ * context that expects a zero-arg getter.
+ *
+ * @example
+ * ```ts
+ * import { async } from "elements-kit/utilities/async";
+ *
+ * const load = async((id: string) => fetch(`/u/${id}`).then(r => r.json()));
+ * load.run("alice");
+ *
+ * // Read as a signal — subscribes to result changes
+ * effect(() => console.log(load()));
+ * await load; // Await the current run — works like a normal promise
+ * ```
+ */
 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

@@ -2,6 +2,26 @@ import { g as untracked, m as signal, s as effect } from "../lib-D6duEs38.mjs";
 import { resolve } from "../signals/index.mjs";
 import { promise } from "./promise.mjs";
 //#region src/utilities/async.ts
+/**
+* Reactive wrapper around an async function. Exposes the current run as
+* reactive signals (`state`, `value`, `reason`, `result`, `pending`) and
+* lets you `run`/`start`/`stop` the underlying task imperatively.
+*
+* Prefer the {@link async} factory — it returns an `Async` that is also
+* callable as a signal (`op()` === `op.result`), which is what most call
+* sites want. Use this class directly only when you need the object form.
+*
+* @example
+* ```ts
+* import { Async } from "elements-kit/utilities/async";
+*
+* const loader = new Async<string, User>(fetchUser);
+* loader.run("alice");
+* effect(() => {
+*   if (loader.state === "fulfilled") console.log(loader.value);
+* });
+* ```
+*/
 var Async = class {
 	#fn = signal(async () => Promise.resolve(void 0));
 	#cleanup = () => {};
@@ -97,6 +117,23 @@ const ASYNC_KEYS = new Set([
 	"raw",
 	Symbol.dispose
 ]);
+/**
+* Create an {@link Async} that is also callable as a signal: invoking it
+* (with no args) reads the current `result`, so it drops into any reactive
+* context that expects a zero-arg getter.
+*
+* @example
+* ```ts
+* import { async } from "elements-kit/utilities/async";
+*
+* const load = async((id: string) => fetch(`/u/${id}`).then(r => r.json()));
+* load.run("alice");
+*
+* // Read as a signal — subscribes to result changes
+* effect(() => console.log(load()));
+* await load; // Await the current run — works like a normal promise
+* ```
+*/
 function async(fn) {
 	const inst = new Async(fn);
 	const signal = () => inst.result;

package/dist/utilities/debounced.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/debounced.d.ts
 /**
@@ -6,6 +6,17 @@ import { y as Computed } from "../infer-Dv5Wk-7E.mjs";
  * milliseconds of silence (i.e. no new values from `getter`).
  *
  * The initial value is read synchronously, so the computed is never undefined.
+ *
+ * @example
+ * ```ts
+ * import { signal } from "elements-kit/signals";
+ * import { createDebounced } from "elements-kit/utilities/debounced";
+ *
+ * const query = signal("");
+ * const debounced = createDebounced(query, 300);
+ *
+ * effect(() => fetch(`/search?q=${debounced()}`));
+ * ```
  */
 declare function createDebounced<T>(getter: () => T, delay: number | (() => number)): Computed<T>;
 //#endregion

package/dist/utilities/debounced.mjs

@@ -7,6 +7,17 @@ import { createTimeout } from "./timeout.mjs";
 * milliseconds of silence (i.e. no new values from `getter`).
 *
 * The initial value is read synchronously, so the computed is never undefined.
+*
+* @example
+* ```ts
+* import { signal } from "elements-kit/signals";
+* import { createDebounced } from "elements-kit/utilities/debounced";
+*
+* const query = signal("");
+* const debounced = createDebounced(query, 300);
+*
+* effect(() => fetch(`/search?q=${debounced()}`));
+* ```
 */
 function createDebounced(getter, delay) {
 	const s = signal(getter());

package/dist/utilities/element-rect.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/element-rect.d.ts
 type RectResult = {

package/dist/utilities/element-scroll.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/element-scroll.d.ts
 type ElementScrollResult = {

package/dist/utilities/environment.d.mts

@@ -1,5 +1,7 @@
 //#region src/utilities/environment.d.ts
+/** `true` when running in a browser (both `window` and `document` exist). */
 declare const isBrowser: boolean;
+/** A shared `Disposable` whose `Symbol.dispose` is a no-op — useful as a safe default. */
 declare const noopDisposable: Disposable;
 //#endregion
 export { isBrowser, noopDisposable };

package/dist/utilities/environment.mjs

@@ -1,5 +1,7 @@
 //#region src/utilities/environment.ts
+/** `true` when running in a browser (both `window` and `document` exist). */
 const isBrowser = typeof window !== "undefined" && typeof document !== "undefined";
+/** A shared `Disposable` whose `Symbol.dispose` is a no-op — useful as a safe default. */
 const noopDisposable = { [Symbol.dispose]() {} };
 //#endregion
 export { isBrowser, noopDisposable };

package/dist/utilities/event-driven.d.mts

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

package/dist/utilities/event-listener.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/event-listener.d.ts
 /**
@@ -7,6 +7,17 @@ import { y as Computed } from "../infer-Dv5Wk-7E.mjs";
  * When called inside an `effect` or `effectScope` the listener is removed
  * when the scope is disposed.  When the target is a reactive getter the
  * listener is re-registered whenever the target changes.
+ *
+ * @example
+ * ```ts
+ * import { on } from "elements-kit/utilities/event-listener";
+ *
+ * // Static target — listener removed when the enclosing scope ends
+ * on(window, "resize", () => console.log(window.innerWidth));
+ *
+ * // Reactive target — listener follows the current element
+ * on(activeElement, "focus", () => console.log("focused"));
+ * ```
  */
 declare function on<K extends keyof HTMLElementEventMap>(target: HTMLElement | Computed<HTMLElement | null>, type: K, handler: (e: HTMLElementEventMap[K]) => void, options?: AddEventListenerOptions): () => void;
 declare function on<K extends keyof DocumentEventMap>(target: Document | Computed<Document | null>, type: K, handler: (e: DocumentEventMap[K]) => void, options?: AddEventListenerOptions): () => void;

package/dist/utilities/focus-within.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/focus-within.d.ts
 /**

package/dist/utilities/hover.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/hover.d.ts
 /**

package/dist/utilities/interval.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/interval.d.ts
 type IntervalResult = {
@@ -12,6 +12,19 @@ type Fn = () => void;
 type Delay = number | (() => number);
 /**
  * Pausable `setInterval` wrapper.  Starts running immediately on creation.
+ *
+ * @example
+ * ```ts
+ * import { createInterval } from "elements-kit/utilities/interval";
+ *
+ * // Reactive clock — updates a signal every second
+ * const { timestamp, stop } = createInterval(1000);
+ * effect(() => console.log(new Date(timestamp())));
+ *
+ * // With a callback
+ * const beat = createInterval(() => beatCount(beatCount() + 1), 500);
+ * beat.stop();
+ * ```
  */
 declare function createInterval(delay: Delay): IntervalResult;
 declare function createInterval(callback: Fn, delay: Delay): IntervalResult;

package/dist/utilities/location.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/location.d.ts
 type LocationResult = {

package/dist/utilities/media-devices.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/media-devices.d.ts
 /**

package/dist/utilities/media-player.d.mts

@@ -1,4 +1,4 @@
-import { x as Signal, y as Computed } from "../infer-Dv5Wk-7E.mjs";
+import { x as Signal, y as Computed } from "../infer-DuFY-y2b.mjs";
 
 //#region src/utilities/media-player.d.ts
 type MediaPlayerResult<T extends HTMLMediaElement> = {

package/dist/utilities/media-query.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/media-query.d.ts
 /**

package/dist/utilities/network.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/network.d.ts
 /**

package/dist/utilities/orientation.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/orientation.d.ts
 type OrientationResult = {

package/dist/utilities/previous.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/previous.d.ts
 /**
@@ -6,6 +6,18 @@ import { y as Computed } from "../infer-Dv5Wk-7E.mjs";
  * Starts as `undefined` until the source changes for the first time.
  *
  * When `ignore` is provided, the previous value only updates when the ignore check fails.
+ *
+ * @example
+ * ```ts
+ * import { signal } from "elements-kit/signals";
+ * import { createPrevious } from "elements-kit/utilities/previous";
+ *
+ * const count = signal(0);
+ * const prev = createPrevious(count);
+ *
+ * count(1); prev(); // 0
+ * count(2); prev(); // 1
+ * ```
  */
 declare function createPrevious<T>(source: Computed<T>, ignore?: (a: T, b: T) => boolean): Computed<T | undefined>;
 //#endregion

package/dist/utilities/previous.mjs

@@ -6,6 +6,18 @@ import "../signals/index.mjs";
 * Starts as `undefined` until the source changes for the first time.
 *
 * When `ignore` is provided, the previous value only updates when the ignore check fails.
+*
+* @example
+* ```ts
+* import { signal } from "elements-kit/signals";
+* import { createPrevious } from "elements-kit/utilities/previous";
+*
+* const count = signal(0);
+* const prev = createPrevious(count);
+*
+* count(1); prev(); // 0
+* count(2); prev(); // 1
+* ```
 */
 function createPrevious(source, ignore) {
 	const prev = signal(void 0);

package/dist/utilities/promise.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/promise.d.ts
 /**
@@ -28,6 +28,12 @@ declare class ReactivePromise<T, E = unknown> extends Promise<T> {
   constructor(executor: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: any) => void) => void);
   static from<T, E = unknown>(p: Promise<T>): ReactivePromise<T, E>;
 }
+/**
+ * A {@link ReactivePromise} that is also callable as a `Computed<T | E | undefined>`.
+ *
+ * Invoking it (`p()`) reads the current `.result` — so it drops into any
+ * reactive context that expects a zero-arg getter.
+ */
 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;
 /**