elements-kit 0.0.20 → 0.2.0

package/dist/utilities/active-element.d.mts

@@ -1,4 +1,4 @@
-import { y as Computed } from "../infer-DuFY-y2b.mjs";
+import { y as Computed } from "../infer-BUUWMoG9.mjs";
 
 //#region src/utilities/active-element.d.ts
 declare const activeElement: Computed<Element | null>;

package/dist/utilities/active-element.test.mjs

@@ -1,4 +1,5 @@
-import { o as describe, s as it, t as globalExpect } from "../test.BmQO5GaM-BeO5pvCo.mjs";
+import { f as it, l as describe } from "../benchmark.CX_oY03V-CsUg-gW0.mjs";
+import { t as globalExpect } from "../test.BmQO5GaM-ZC2MPXQb.mjs";
 import { activeElement } from "./active-element.mjs";
 //#region src/utilities/active-element.test.ts
 describe("activeElement (singleton)", () => {

package/dist/utilities/async.d.mts

@@ -1,4 +1,4 @@
-import { b as MaybeReactive } from "../infer-DuFY-y2b.mjs";
+import { b as MaybeReactive } from "../infer-BUUWMoG9.mjs";
 import { ComputedPromise } from "./promise.mjs";
 
 //#region src/utilities/async.d.ts

package/dist/utilities/async.test.mjs

@@ -1,6 +1,7 @@
 import { m as signal, p as onCleanup, s as effect } from "../lib-D6duEs38.mjs";
 import "../signals/index.mjs";
-import { n as vi, o as describe, s as it, t as globalExpect } from "../test.BmQO5GaM-BeO5pvCo.mjs";
+import { f as it, l as describe } from "../benchmark.CX_oY03V-CsUg-gW0.mjs";
+import { n as vi, t as globalExpect } from "../test.BmQO5GaM-ZC2MPXQb.mjs";
 import { Async, async } from "./async.mjs";
 import { createInterval } from "./interval.mjs";
 //#region src/utilities/async.test.ts

package/dist/utilities/context.d.mts

@@ -0,0 +1,78 @@
+//#region src/utilities/context.d.ts
+/**
+ * Register `value` under `key` on `host`. Calls to {@link getContext} from
+ * any descendant of `host` (in the DOM tree, including across open shadow
+ * roots) resolve to this value, unless an inner provider with the same key
+ * shadows it. Returns `host` so the call can be used inline.
+ *
+ * Must be called inside an `effect` / `effectScope` (or a wrapped
+ * `connectedCallback`). The entry is auto-removed via `onCleanup` when the
+ * surrounding scope disposes. Passes `null` through unchanged.
+ *
+ * @example
+ * Inline form — `setContext` returns the host so it composes directly:
+ * ```tsx
+ * import { signal } from "elements-kit/signals";
+ * import { setContext } from "elements-kit/utilities/context";
+ *
+ * const THEME = Symbol("theme");
+ *
+ * function ThemeProvider({ children }: { children: JSX.Element }) {
+ *   const theme = signal<"light" | "dark">("dark");
+ *   return setContext(<div>{children}</div>, THEME, theme);
+ * }
+ * ```
+ *
+ * @example
+ * Equivalent `ref` form:
+ * ```tsx
+ * function ThemeProvider({ children }: { children: JSX.Element }) {
+ *   const theme = signal<"light" | "dark">("dark");
+ *   return (
+ *     <div ref={(el) => setContext(el, THEME, theme)}>
+ *       {children}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function setContext<H extends EventTarget | null, T>(host: H, key: PropertyKey, value: T): H;
+/**
+ * Walk up from `consumer` (across open shadow boundaries via
+ * `getRootNode().host`) and return the first registered value for `key`,
+ * or `undefined`.
+ *
+ * One-shot — does not subscribe to anything. If `value` is a
+ * `Signal`/`Computed`, the caller reads it inside their own `effect` for
+ * reactivity.
+ *
+ * @example
+ * Inside a custom element's `connectedCallback`:
+ * ```ts
+ * const theme = getContext<() => "light" | "dark">(this, THEME);
+ * effect(() => { this.dataset.theme = theme?.() ?? "light"; });
+ * ```
+ *
+ * @example
+ * From a JSX component — defer the lookup with `<dom-lifecycle>`, since `ref`
+ * runs before the element is inserted:
+ * ```tsx
+ * import { signal, type Signal } from "elements-kit/signals";
+ * import "elements-kit/utilities/dom-lifecycle";
+ *
+ * function ThemeConsumer() {
+ *   const theme = signal<Signal<"light" | "dark"> | undefined>(undefined);
+ *   return (
+ *     <div>
+ *       <dom-lifecycle
+ *         onConnect={(el) => theme(getContext(el, THEME))}
+ *       />
+ *       {() => theme()?.() ?? "light"}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function getContext<T>(consumer: Element, key: PropertyKey): T | undefined;
+//#endregion
+export { getContext, setContext };

package/dist/utilities/context.mjs

@@ -0,0 +1,115 @@
+import { m as signal, p as onCleanup } from "../lib-D6duEs38.mjs";
+import "../signals/index.mjs";
+//#region src/utilities/context.ts
+const registry = /* @__PURE__ */ new WeakMap();
+const versions = /* @__PURE__ */ new Map();
+function version(key) {
+	let v = versions.get(key);
+	if (!v) versions.set(key, v = signal(0));
+	return v;
+}
+/**
+* Register `value` under `key` on `host`. Calls to {@link getContext} from
+* any descendant of `host` (in the DOM tree, including across open shadow
+* roots) resolve to this value, unless an inner provider with the same key
+* shadows it. Returns `host` so the call can be used inline.
+*
+* Must be called inside an `effect` / `effectScope` (or a wrapped
+* `connectedCallback`). The entry is auto-removed via `onCleanup` when the
+* surrounding scope disposes. Passes `null` through unchanged.
+*
+* @example
+* Inline form — `setContext` returns the host so it composes directly:
+* ```tsx
+* import { signal } from "elements-kit/signals";
+* import { setContext } from "elements-kit/utilities/context";
+*
+* const THEME = Symbol("theme");
+*
+* function ThemeProvider({ children }: { children: JSX.Element }) {
+*   const theme = signal<"light" | "dark">("dark");
+*   return setContext(<div>{children}</div>, THEME, theme);
+* }
+* ```
+*
+* @example
+* Equivalent `ref` form:
+* ```tsx
+* function ThemeProvider({ children }: { children: JSX.Element }) {
+*   const theme = signal<"light" | "dark">("dark");
+*   return (
+*     <div ref={(el) => setContext(el, THEME, theme)}>
+*       {children}
+*     </div>
+*   );
+* }
+* ```
+*/
+function setContext(host, key, value) {
+	if (host == null) return host;
+	let map = registry.get(host);
+	if (!map) registry.set(host, map = /* @__PURE__ */ new Map());
+	map.set(key, value);
+	const owned = map;
+	const v = version(key);
+	v(v() + 1);
+	onCleanup(() => {
+		owned.delete(key);
+		if (owned.size === 0) registry.delete(host);
+		v(v() + 1);
+	});
+	return host;
+}
+/**
+* Walk up from `consumer` (across open shadow boundaries via
+* `getRootNode().host`) and return the first registered value for `key`,
+* or `undefined`.
+*
+* One-shot — does not subscribe to anything. If `value` is a
+* `Signal`/`Computed`, the caller reads it inside their own `effect` for
+* reactivity.
+*
+* @example
+* Inside a custom element's `connectedCallback`:
+* ```ts
+* const theme = getContext<() => "light" | "dark">(this, THEME);
+* effect(() => { this.dataset.theme = theme?.() ?? "light"; });
+* ```
+*
+* @example
+* From a JSX component — defer the lookup with `<dom-lifecycle>`, since `ref`
+* runs before the element is inserted:
+* ```tsx
+* import { signal, type Signal } from "elements-kit/signals";
+* import "elements-kit/utilities/dom-lifecycle";
+*
+* function ThemeConsumer() {
+*   const theme = signal<Signal<"light" | "dark"> | undefined>(undefined);
+*   return (
+*     <div>
+*       <dom-lifecycle
+*         onConnect={(el) => theme(getContext(el, THEME))}
+*       />
+*       {() => theme()?.() ?? "light"}
+*     </div>
+*   );
+* }
+* ```
+*/
+function getContext(consumer, key) {
+	version(key)();
+	let node = consumer;
+	while (node) {
+		const map = registry.get(node);
+		if (map?.has(key)) return map.get(key);
+		const parent = node.parentNode;
+		if (parent) {
+			node = parent;
+			continue;
+		}
+		const root = node.getRootNode();
+		node = root instanceof ShadowRoot ? root.host : null;
+	}
+}
+//#endregion
+export { getContext, setContext };

package/dist/utilities/context.test.d.mts

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

package/dist/utilities/context.test.mjs

@@ -0,0 +1,171 @@
+import { c as effectScope, m as signal, s as effect } from "../lib-D6duEs38.mjs";
+import "../signals/index.mjs";
+import { f as it, l as describe, o as afterEach } from "../benchmark.CX_oY03V-CsUg-gW0.mjs";
+import { n as vi, t as globalExpect } from "../test.BmQO5GaM-ZC2MPXQb.mjs";
+import { getContext, setContext } from "./context.mjs";
+//#region src/utilities/context.test.ts
+afterEach(() => {
+	document.body.innerHTML = "";
+});
+describe("context", () => {
+	it("returns undefined when no provider exists above the consumer", () => {
+		const el = document.createElement("div");
+		document.body.appendChild(el);
+		globalExpect(getContext(el, "missing")).toBeUndefined();
+	});
+	it("resolves a value across one parent boundary", () => {
+		const host = document.createElement("section");
+		const child = document.createElement("span");
+		host.appendChild(child);
+		document.body.appendChild(host);
+		effectScope(() => {
+			setContext(host, "k", 42);
+		});
+		globalExpect(getContext(child, "k")).toBe(42);
+	});
+	it("propagates updates when the value is a Signal", () => {
+		const host = document.createElement("section");
+		const child = document.createElement("span");
+		host.appendChild(child);
+		document.body.appendChild(host);
+		const value = signal(1);
+		const seen = vi.fn();
+		effectScope(() => {
+			setContext(host, "n", value);
+		});
+		effect(() => {
+			seen(getContext(child, "n")?.());
+		});
+		globalExpect(seen).toHaveBeenLastCalledWith(1);
+		value(2);
+		globalExpect(seen).toHaveBeenLastCalledWith(2);
+	});
+	it("innermost provider wins when nested with the same key", () => {
+		const outer = document.createElement("section");
+		const inner = document.createElement("section");
+		const leaf = document.createElement("span");
+		outer.appendChild(inner);
+		inner.appendChild(leaf);
+		document.body.appendChild(outer);
+		effectScope(() => {
+			setContext(outer, "k", "outer");
+			setContext(inner, "k", "inner");
+		});
+		globalExpect(getContext(leaf, "k")).toBe("inner");
+	});
+	it("disposing the provider's scope removes the entry and falls through", () => {
+		const outer = document.createElement("section");
+		const inner = document.createElement("section");
+		const leaf = document.createElement("span");
+		outer.appendChild(inner);
+		inner.appendChild(leaf);
+		document.body.appendChild(outer);
+		const stopOuter = effectScope(() => {
+			setContext(outer, "k", "outer");
+		});
+		const stopInner = effectScope(() => {
+			setContext(inner, "k", "inner");
+		});
+		globalExpect(getContext(leaf, "k")).toBe("inner");
+		stopInner();
+		globalExpect(getContext(leaf, "k")).toBe("outer");
+		stopOuter();
+		globalExpect(getContext(leaf, "k")).toBeUndefined();
+	});
+	it("distinct keys do not cross-talk", () => {
+		const host = document.createElement("section");
+		const child = document.createElement("span");
+		host.appendChild(child);
+		document.body.appendChild(host);
+		const A = Symbol("a");
+		const B = Symbol("b");
+		effectScope(() => {
+			setContext(host, A, "value-a");
+			setContext(host, B, "value-b");
+		});
+		globalExpect(getContext(child, A)).toBe("value-a");
+		globalExpect(getContext(child, B)).toBe("value-b");
+		globalExpect(getContext(child, "c")).toBeUndefined();
+	});
+	it("crosses an open shadow root via getRootNode().host", () => {
+		const host = document.createElement("section");
+		const shadow = host.attachShadow({ mode: "open" });
+		const inner = document.createElement("span");
+		shadow.appendChild(inner);
+		document.body.appendChild(host);
+		effectScope(() => {
+			setContext(host, "k", "from-host");
+		});
+		globalExpect(getContext(inner, "k")).toBe("from-host");
+	});
+	it("moving the consumer picks up the new ancestor on next get", () => {
+		const a = document.createElement("section");
+		const b = document.createElement("section");
+		const leaf = document.createElement("span");
+		a.appendChild(leaf);
+		document.body.append(a, b);
+		effectScope(() => {
+			setContext(a, "k", "a");
+			setContext(b, "k", "b");
+		});
+		globalExpect(getContext(leaf, "k")).toBe("a");
+		b.appendChild(leaf);
+		globalExpect(getContext(leaf, "k")).toBe("b");
+	});
+	it("returns undefined for an orphan element not in any tree", () => {
+		globalExpect(getContext(document.createElement("div"), "k")).toBeUndefined();
+	});
+	it("two providers with different keys in the same subtree both resolve", () => {
+		const host = document.createElement("section");
+		const leaf = document.createElement("span");
+		host.appendChild(leaf);
+		document.body.appendChild(host);
+		effectScope(() => {
+			setContext(host, "x", 1);
+			setContext(host, "y", 2);
+		});
+		globalExpect(getContext(leaf, "x")).toBe(1);
+		globalExpect(getContext(leaf, "y")).toBe(2);
+	});
+	describe("with <dom-lifecycle> as wrapper", () => {
+		it("descendants resolve a context set on the lifecycle wrapper itself", () => {
+			const wrapper = document.createElement("dom-lifecycle");
+			const consumer = document.createElement("button");
+			wrapper.appendChild(consumer);
+			document.body.appendChild(wrapper);
+			effectScope(() => {
+				setContext(wrapper, "theme", "dark");
+			});
+			globalExpect(getContext(consumer, "theme")).toBe("dark");
+		});
+		it("the wrapper is transparent in the ancestor walk — outer providers still resolve", () => {
+			const provider = document.createElement("section");
+			document.body.appendChild(provider);
+			effectScope(() => {
+				setContext(provider, "theme", "outer");
+			});
+			const wrapper = document.createElement("dom-lifecycle");
+			const consumer = document.createElement("button");
+			wrapper.appendChild(consumer);
+			provider.appendChild(wrapper);
+			globalExpect(getContext(consumer, "theme")).toBe("outer");
+		});
+		it("the wrapper shadows an outer provider when both register the same key", () => {
+			const provider = document.createElement("section");
+			document.body.appendChild(provider);
+			effectScope(() => {
+				setContext(provider, "theme", "outer");
+			});
+			const wrapper = document.createElement("dom-lifecycle");
+			const consumer = document.createElement("button");
+			wrapper.appendChild(consumer);
+			provider.appendChild(wrapper);
+			effectScope(() => {
+				setContext(wrapper, "theme", "inner");
+			});
+			globalExpect(getContext(consumer, "theme")).toBe("inner");
+		});
+	});
+});
+//#endregion
+export {};

package/dist/utilities/debounced.d.mts

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

package/dist/utilities/debounced.test.mjs

@@ -1,6 +1,7 @@
 import { c as effectScope, m as signal } from "../lib-D6duEs38.mjs";
 import "../signals/index.mjs";
-import { a as beforeEach, n as vi, o as describe, r as afterEach, s as it, t as globalExpect } from "../test.BmQO5GaM-BeO5pvCo.mjs";
+import { c as beforeEach, f as it, l as describe, o as afterEach } from "../benchmark.CX_oY03V-CsUg-gW0.mjs";
+import { n as vi, t as globalExpect } from "../test.BmQO5GaM-ZC2MPXQb.mjs";
 import { createDebounced } from "./debounced.mjs";
 //#region src/utilities/debounced.test.ts
 beforeEach(() => {

package/dist/utilities/dom-lifecycle.bench.d.mts

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

package/dist/utilities/dom-lifecycle.bench.mjs

@@ -0,0 +1,90 @@
+import { l as describe, t as bench } from "../benchmark.CX_oY03V-CsUg-gW0.mjs";
+//#region src/utilities/dom-lifecycle.bench.ts
+describe("dom-lifecycle — registration cost", () => {
+	bench("register 100 entries on already-connected elements", () => {
+		document.body.innerHTML = "";
+		for (let i = 0; i < 100; i++) {
+			const el = document.createElement("div");
+			document.body.appendChild(el);
+			const probe = document.createElement("dom-lifecycle");
+			probe.onConnect = () => {};
+			el.appendChild(probe);
+		}
+	}, { iterations: 50 });
+});
+describe("dom-lifecycle — connect+disconnect cycle over N pre-staged entries", () => {
+	for (const N of [
+		10,
+		100,
+		1e3,
+		1e4
+	]) {
+		let wrapper;
+		bench(`cycle ${N} entries`, () => {
+			document.body.appendChild(wrapper);
+			wrapper.remove();
+		}, {
+			iterations: N >= 1e4 ? 30 : 50,
+			setup: () => {
+				document.body.innerHTML = "";
+				wrapper = document.createElement("div");
+				for (let i = 0; i < N; i++) {
+					const el = document.createElement("div");
+					wrapper.appendChild(el);
+					const probe = document.createElement("dom-lifecycle");
+					probe.onConnect = () => {};
+					probe.onDisconnect = () => {};
+					el.appendChild(probe);
+				}
+			},
+			teardown: () => {
+				document.body.innerHTML = "";
+			}
+		});
+	}
+});
+describe("dom-lifecycle — single mutation, N inert page entries", () => {
+	for (const N of [
+		0,
+		100,
+		1e3,
+		1e4
+	]) {
+		let probe;
+		bench(`single mutation with ${N} other entries`, () => {
+			document.body.appendChild(probe);
+			probe.remove();
+		}, {
+			iterations: 50,
+			setup: () => {
+				document.body.innerHTML = "";
+				for (let i = 0; i < N; i++) {
+					const el = document.createElement("div");
+					document.body.appendChild(el);
+					const p = document.createElement("dom-lifecycle");
+					p.onConnect = () => {};
+					el.appendChild(p);
+				}
+				probe = document.createElement("span");
+			},
+			teardown: () => {
+				document.body.innerHTML = "";
+			}
+		});
+	}
+});
+describe("dom-lifecycle — single-entry connect/disconnect cycle", () => {
+	bench("create → append → remove → append (single entry)", () => {
+		document.body.innerHTML = "";
+		const el = document.createElement("div");
+		const probe = document.createElement("dom-lifecycle");
+		probe.onConnect = () => {};
+		probe.onDisconnect = () => {};
+		el.appendChild(probe);
+		document.body.appendChild(el);
+		el.remove();
+		document.body.appendChild(el);
+	}, { iterations: 50 });
+});
+//#endregion
+export {};

package/dist/utilities/dom-lifecycle.d.mts

@@ -0,0 +1,88 @@
+//#region src/utilities/dom-lifecycle.d.ts
+type LifecycleCallback = (self: DomLifecycleElement) => void;
+type AdoptedCallback = (oldDocument: Document, newDocument: Document) => void;
+/**
+ * Custom element backing the `<dom-lifecycle>` JSX tag. Place inside any
+ * element to receive lifecycle notifications for that surrounding subtree —
+ * `onConnect` / `onDisconnect` mirror `connectedCallback` /
+ * `disconnectedCallback`, `onMove` mirrors the upcoming `connectedMoveCallback`
+ * (fires when the element is moved with `Node.moveBefore()` instead of
+ * disconnect+connect), and `onAdopted` mirrors `adoptedCallback`.
+ *
+ * Position-tracking callbacks (`onConnect` / `onDisconnect` / `onMove`)
+ * receive the lifecycle element itself. Read `self.parentElement` for the
+ * surrounding element, `self.firstElementChild` / `self.children` for a
+ * wrapped subtree, or `self.getRootNode()` to walk through a shadow root.
+ * `self` is always the live element — non-null even when the lifecycle
+ * element is the root of a shadow tree (where `parentElement` is `null`).
+ *
+ * If you need the connect-time parent inside `onDisconnect` (the spec sets
+ * `parentElement` to `null` before `disconnectedCallback` runs), capture it
+ * yourself in `onConnect`.
+ *
+ * `onConnect` runs inside an `effectScope`, so any `onCleanup` registered
+ * inside it (directly or via factories like `setContext`, `on`, observers,
+ * etc.) fires on disconnect — before `onDisconnect` is invoked. The scope
+ * persists across moves (`onMove`); a fresh scope is created on every
+ * reconnection.
+ *
+ * Layout / a11y inert by default: `display: contents` removes the box so the
+ * element doesn't affect its parent's layout, and `role="none"` strips its
+ * implicit role from the accessibility tree. Children still participate in
+ * both layout and a11y. (CSS structural selectors like `:empty`,
+ * `:first-child`, and `:nth-child` still see the element in the DOM tree —
+ * place the lifecycle element where those selectors don't reach if needed.)
+ *
+ * @example
+ * ```tsx
+ * <div>
+ *   <dom-lifecycle
+ *     onConnect={(el) => el.parentElement?.classList.add("ready")}
+ *     onDisconnect={(el) => {
+ *       // el.parentElement is null here per spec — stash from onConnect if needed
+ *     }}
+ *   />
+ * </div>
+ * ```
+ *
+ * @example
+ * Wrap children — read the wrapped subtree via `firstElementChild`:
+ * ```tsx
+ * <section>
+ *   <dom-lifecycle onConnect={(el) => measure(el.firstElementChild)}>
+ *     <h1>Title</h1>
+ *     <p>Body</p>
+ *   </dom-lifecycle>
+ * </section>
+ * ```
+ */
+declare class DomLifecycleElement extends HTMLElement {
+  #private;
+  constructor();
+  set onConnect(fn: LifecycleCallback | null);
+  get onConnect(): LifecycleCallback | null;
+  set onDisconnect(fn: LifecycleCallback | null);
+  get onDisconnect(): LifecycleCallback | null;
+  set onMove(fn: LifecycleCallback | null);
+  get onMove(): LifecycleCallback | null;
+  set onAdopted(fn: AdoptedCallback | null);
+  get onAdopted(): AdoptedCallback | null;
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  connectedMoveCallback(): void;
+  adoptedCallback(oldDocument: Document, newDocument: Document): void;
+}
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      "dom-lifecycle": {
+        onConnect?: LifecycleCallback;
+        onDisconnect?: LifecycleCallback;
+        onMove?: LifecycleCallback;
+        onAdopted?: AdoptedCallback;
+      };
+    }
+  }
+}
+//#endregion
+export { DomLifecycleElement };