elements-kit 0.19.0 → 0.21.0

package/README.md

@@ -67,7 +67,11 @@ Every feature is a separate subpath export — import only what you use.
 | `elements-kit/custom-elements` | `defineElement`, `CustomElementRegistry` |
 | `elements-kit/for` | `For` keyed-list component |
 | `elements-kit/jsx-runtime` | JSX factory + type helpers (`ElementProps`, `Props`, `ComponentProps`, `MaybeReactiveProps`, `ReactiveProps`, `Require`) — configure via `jsxImportSource` |
+| `elements-kit/server` | `renderToStream`, `renderToString` — streaming HTML rendering in any JS runtime (Node, edge/Workers), no DOM required *(experimental)* |
+| `elements-kit/hydrate` | `hydrate(container, () => <App/>)` — adopt server-rendered DOM and make it interactive *(experimental)* |
+| `elements-kit/await` | `Await` — loading boundary (Suspense equivalent); code splitting = `async` + dynamic import *(experimental)* |
 | `elements-kit/integrations/react` | `useSignal`, `useScope` React bridge hooks |
+| `elements-kit/integrations/astro` | `elementsKit()` Astro integration — elements-kit components as server-rendered, hydrated islands *(experimental)* |
 | `elements-kit/utilities/*` | Reactive browser-API utilities — see [src/utilities/README.md](src/utilities/README.md) |
 
 ## Signals
@@ -488,6 +492,16 @@ class XPicker extends HTMLElement {
 // ElementProps<typeof XPicker> now includes `on:commit`
 ```
 
+## Roadmap
+
+Directions under consideration for the SSR/islands layer (nothing here is committed):
+
+- **Declarative Shadow DOM & custom-element SSR** — emit `<template shadowrootmode>` on the server and claim shadow roots at hydration, so elements-kit custom elements server-render inside *any* framework's HTML.
+- **`ErrorBoundary` + `Await` error fallback** — first-class rejection handling; today a rejected awaitable settles into its reason.
+- **Out-of-order streaming + richer `ek-data` serialization** — stream fallbacks immediately and swap content in when ready (today `Await` holds the stream); serialize Dates/Maps/cyclic values instead of JSON-only.
+- **Astro extras** — View Transitions survival, a custom `client:interaction` directive, a live `server:defer` demo.
+- **Hardening toward stable** — real-Astro end-to-end tests in CI (dev + build/preview), an Astro renderer-contract type-pin, SSR↔client parity and escaping property tests, seeding-alignment and stream-robustness suites. The `server` / `hydrate` / `await` / `integrations/astro` entries drop their *experimental* badges when this lands.
+
 ## Learn more
 
 - [Documentation site](docs/) — guides, playgrounds, reference

package/dist/await.d.mts

@@ -0,0 +1,53 @@
+import { t as Child } from "./types-CUvFIgPa.mjs";
+
+//#region src/await.d.ts
+/** @internal Metadata stamped on an Await region getter (see claim walk). */
+interface AsyncRegionMeta {
+  /** ek-data ids the server consumed for this region. */
+  ids: number;
+  /** True while any of the region's awaitables is pending. */
+  pending(): boolean;
+}
+/**
+ * Loading boundary for async children — elements-kit's `Suspense` equivalent.
+ *
+ * Direct async children (`promise`/`async` values — including the
+ * code-splitting pattern `async(() => import("./chart"))`) are detected
+ * automatically; pass `when` to gate on arbitrary awaitables instead. While
+ * anything is pending the client renders `fallback`; once everything settles
+ * the children show. The server never renders the fallback — the stream
+ * awaits and emits the real content. During hydration the server content
+ * stays visible while the region is pending (no fallback flash).
+ *
+ * Prefer a thunk fallback (`fallback={() => <Spinner/>}`) so it renders
+ * fresh each time the boundary re-enters a pending state.
+ *
+ * @example Code splitting with `async` + dynamic import:
+ * ```tsx
+ * const chart = async(() => import("./chart").then((m) => m.default));
+ *
+ * function Panel() {
+ *   chart.run(); // server: awaited · hydration: deferred · client: import
+ *   return (
+ *     <Await fallback={() => <em>loading…</em>}>{chart}</Await>
+ *   );
+ * }
+ * ```
+ *
+ * @example Passing props to a code-split component:
+ * ```tsx
+ * const chart = async(() => import("./chart").then((m) => m.default));
+ * chart.run();
+ *
+ * <Await fallback={() => <em>loading…</em>}>
+ *   {promise(chart.then((C) => () => <C data={data} />))}
+ * </Await>
+ * ```
+ */
+declare function Await(props: {
+  fallback?: Child | (() => Child);
+  when?: unknown;
+  children?: Child;
+}): Element;
+//#endregion
+export { AsyncRegionMeta, Await };

package/dist/await.mjs

@@ -0,0 +1,70 @@
+import { f as effectsInert, t as ASYNC_REGION } from "./lib-DYypKhxk.mjs";
+import { isReactive } from "./signals/index.mjs";
+import { isReactivePromiseLike, promise } from "./utilities/promise.mjs";
+import { isAsyncLike } from "./utilities/async.mjs";
+//#region src/await.ts
+function isThenable(value) {
+	return value != null && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
+}
+function toAwaitables(value) {
+	const list = Array.isArray(value) ? value.flat(Infinity) : [value];
+	const out = [];
+	for (const item of list) if (isReactivePromiseLike(item) || isAsyncLike(item)) out.push(item);
+	else if (isThenable(item)) out.push(promise(item));
+	return out;
+}
+/**
+* Loading boundary for async children — elements-kit's `Suspense` equivalent.
+*
+* Direct async children (`promise`/`async` values — including the
+* code-splitting pattern `async(() => import("./chart"))`) are detected
+* automatically; pass `when` to gate on arbitrary awaitables instead. While
+* anything is pending the client renders `fallback`; once everything settles
+* the children show. The server never renders the fallback — the stream
+* awaits and emits the real content. During hydration the server content
+* stays visible while the region is pending (no fallback flash).
+*
+* Prefer a thunk fallback (`fallback={() => <Spinner/>}`) so it renders
+* fresh each time the boundary re-enters a pending state.
+*
+* @example Code splitting with `async` + dynamic import:
+* ```tsx
+* const chart = async(() => import("./chart").then((m) => m.default));
+*
+* function Panel() {
+*   chart.run(); // server: awaited · hydration: deferred · client: import
+*   return (
+*     <Await fallback={() => <em>loading…</em>}>{chart}</Await>
+*   );
+* }
+* ```
+*
+* @example Passing props to a code-split component:
+* ```tsx
+* const chart = async(() => import("./chart").then((m) => m.default));
+* chart.run();
+*
+* <Await fallback={() => <em>loading…</em>}>
+*   {promise(chart.then((C) => () => <C data={data} />))}
+* </Await>
+* ```
+*/
+function Await(props) {
+	const read = (value) => typeof value === "function" && !isReactive(value) ? value() : value;
+	const children = read(props.children);
+	const when = read(props.when);
+	const fromChildren = toAwaitables(children);
+	const awaitables = when != null ? toAwaitables(when) : fromChildren;
+	if (awaitables.length === 0) return children;
+	if (effectsInert()) return promise(Promise.all(awaitables).then(() => () => children));
+	const fallback = props.fallback;
+	const pending = () => awaitables.some((a) => a.state === "pending");
+	const region = () => pending() ? read(fallback) : children;
+	region[ASYNC_REGION] = {
+		ids: 1 + fromChildren.length,
+		pending
+	};
+	return region;
+}
+//#endregion
+export { Await };

package/dist/{custom-elements-D5CgfNKc.d.mts → custom-elements-BGcU6ldL.d.mts}

@@ -19,10 +19,12 @@
  * }
  * ```
  */
+type RegisteredElementInstances = { [K in keyof ElementsKit.CustomElementRegistry]: ElementsKit.CustomElementRegistry[K] extends (abstract new (...args: any[]) => infer I) ? I : never };
 declare global {
   namespace ElementsKit {
     interface CustomElementRegistry {}
   }
+  interface HTMLElementTagNameMap extends RegisteredElementInstances {}
 }
 type CustomElementRegistry = ElementsKit.CustomElementRegistry;
 type AnyCtor = CustomElementConstructor;

package/dist/custom-elements.d.mts

@@ -1,2 +1,2 @@
-import { n as defineElement, t as CustomElementRegistry } from "./custom-elements-D5CgfNKc.mjs";
+import { n as defineElement, t as CustomElementRegistry } from "./custom-elements-BGcU6ldL.mjs";
 export { CustomElementRegistry, defineElement };

package/dist/{element-xQwq4ulc.mjs → element-D3om9yA6.mjs}

@@ -1,8 +1,8 @@
-import { c as effectScope, g as untracked, p as onCleanup, s as effect } from "./lib-Dkc7cV5F.mjs";
+import { C as untracked, _ as onCleanup, d as effectScope, u as effect } from "./lib-DYypKhxk.mjs";
 import "./polyfill-CdZVCxdo.mjs";
 import { isReactive, resolveProps } from "./signals/index.mjs";
 import { on } from "./utilities/event-listener.mjs";
-import { n as Slot, r as resolveNode$1, t as SLOTS } from "./slot-Cne__au7.mjs";
+import { n as Slot, r as resolveNode$1, t as SLOTS } from "./slot-Dvf30O0B.mjs";
 //#region src/jsx-runtime/constants.ts
 /**
 * IDL properties that take precedence over the default `setAttribute` path.
@@ -80,6 +80,59 @@ const Properties = new Set([
 	"sharedstoragewritable",
 	"defaultValue"
 ]);
+/**
+* Content attributes with boolean semantics: presence means true. Emitters
+* write them bare when the value is truthy and omit them entirely when falsy
+* — never `disabled="0"`. Synced from `dom-expressions/src/constants.js`.
+*/
+const BooleanAttributes = new Set([
+	"allowfullscreen",
+	"async",
+	"alpha",
+	"autofocus",
+	"autoplay",
+	"checked",
+	"controls",
+	"default",
+	"disabled",
+	"formnovalidate",
+	"hidden",
+	"indeterminate",
+	"inert",
+	"ismap",
+	"loop",
+	"multiple",
+	"muted",
+	"nomodule",
+	"novalidate",
+	"open",
+	"playsinline",
+	"readonly",
+	"required",
+	"reversed",
+	"seamless",
+	"selected",
+	"adauctionheaders",
+	"browsingtopics",
+	"credentialless",
+	"defaultchecked",
+	"defaultmuted",
+	"defaultselected",
+	"defer",
+	"disablepictureinpicture",
+	"disableremoteplayback",
+	"preservespitch",
+	"shadowrootclonable",
+	"shadowrootcustomelementregistry",
+	"shadowrootdelegatesfocus",
+	"shadowrootserializable",
+	"sharedstoragewritable"
+]);
+/** React-compat property→attribute aliases (dom-expressions `Aliases`). */
+const AttrAliases = {
+	className: "class",
+	htmlFor: "for"
+};
 /** Properties whose assignment replaces the element's children. */
 const ChildProperties = new Set([
 	"innerHTML",
@@ -460,6 +513,17 @@ function setAttribute(el, key, value) {
 	el.setAttribute(key, next);
 }
 //#endregion
+//#region src/jsx-runtime/renderer.ts
+const ACTIVE_RENDERER = Symbol.for("elements-kit.active-renderer");
+const slot = globalThis;
+/** Install or clear (`null`) the active renderer. */
+function setRenderer(renderer) {
+	slot[ACTIVE_RENDERER] = renderer;
+}
+function getRenderer() {
+	return slot[ACTIVE_RENDERER] ?? null;
+}
+//#endregion
 //#region src/jsx-runtime/dispose.ts
 const DISPOSABLES = /* @__PURE__ */ new WeakMap();
 const sharedDispose = function() {
@@ -483,7 +547,10 @@ function attachDisposables(target, disposers) {
 }
 //#endregion
 //#region src/jsx-runtime/element.ts
-function createElement(type, { ref, ...props } = {}) {
+function createElement(type, allProps = {}) {
+	const renderer = getRenderer();
+	if (renderer) return renderer.jsx(type, allProps);
+	const { ref, ...props } = allProps;
 	if (typeof type === "function" && !type.prototype?.render) return createFunctionElement(type, props, ref);
 	return createNodeElement(type, props, ref);
 }
@@ -537,4 +604,4 @@ function renderNode(node) {
 	return renderNode(node.render());
 }
 //#endregion
-export { disposeElement as n, mountChild as r, createElement as t };
+export { mountChild as a, BooleanAttributes as c, applyProps as i, ChildProperties as l, disposeElement as n, resolveChild as o, setRenderer as r, AttrAliases as s, createElement as t, Properties as u };

package/dist/for.d.mts

@@ -1,31 +1,16 @@
-import { i as Props, s as Require } from "./infer-B7T5hi_D.mjs";
+import { _ as Require, m as Props } from "./types-CUvFIgPa.mjs";
 
 //#region src/for.d.ts
 type KeyFn<T> = (item: T, index: number) => string | number;
 type RenderFn<T> = (item: T, index: number) => Element | DocumentFragment | null;
-/**
- * Keyed list renderer. Reconciles a reactive array into the DOM using a key
- * function to match existing nodes — minimising create/destroy churn.
- *
- * Reconciliation strategy (inspired by udomdiff / dom-expressions):
- *   1. Remove stale entries (keys absent from the new array).
- *   2. Skip unchanged common prefix and suffix.
- *   3. Pure-append fast path when the surviving old range is empty.
- *   4. Backward scan of the middle region — move or create entries so that
- *      each entry's range lands immediately before the already-correct cursor.
- *
- * @example
- * ```tsx
- * <For each={visibleTodos} by={(todo) => todo.id}>
- *   {(todo) => <li>{todo.text}</li>}
- * </For>
- * ```
- *
- * Props:
- *   each     — reactive getter returning the array (e.g. a `computed`)
- *   by       — extracts a stable key per item (default: index)
- *   children — render function called once per new key
- */
+interface Entry {
+  /** Marks the start of this item's DOM range. */
+  start: Comment;
+  /** Marks the end of this item's DOM range. */
+  end: Comment;
+  /** Disposes effects/onCleanup registered by the render callback for this item. */
+  dispose: () => void;
+}
 /**
  * Props for `<For>`, derived from its public instance fields.
  * All props are optional — the class initializes sane defaults at runtime.
@@ -65,10 +50,19 @@ declare class For<T = unknown> {
   #private;
   constructor(_props?: ForProps<T>);
   get each(): T[];
-  set each(v: T[]);
+  set each(v: T[] | (() => T[]));
   by: KeyFn<T>;
   children: RenderFn<T>;
   render(): DocumentFragment;
+  /**
+   * @internal Hydrate support: adopt server-rendered range markers and
+   * pre-claimed entries instead of creating a fresh range. The first
+   * reconcile run sees matching key order and performs no DOM operations;
+   * later `each` changes reconcile against the adopted entries as usual.
+   */
+  hydrateRange(start: Comment, end: Comment, entries: ReadonlyMap<string | number, Entry>, order: ReadonlyArray<string | number>): void;
 }
+/** @internal Cross-instance-safe For check (identity or brand). */
+declare function isForComponent(type: unknown): boolean;
 //#endregion
-export { For };
+export { Entry, For, isForComponent };

package/dist/for.mjs

@@ -1,6 +1,6 @@
-import { c as effectScope, g as untracked, h as trigger, m as signal, p as onCleanup, s as effect } from "./lib-Dkc7cV5F.mjs";
+import { C as untracked, S as trigger, _ as onCleanup, d as effectScope, u as effect, x as signal } from "./lib-DYypKhxk.mjs";
 import "./signals/index.mjs";
-import { n as disposeElement } from "./element-xQwq4ulc.mjs";
+import { n as disposeElement } from "./element-D3om9yA6.mjs";
 //#region src/for.ts
 /**
 * Keyed list renderer. See {@link ForProps} for prop details.
@@ -21,7 +21,8 @@ var For = class {
 	constructor(_props) {}
 	#each = signal([]);
 	get each() {
-		return this.#each();
+		const v = this.#each();
+		return typeof v === "function" ? v() : v;
 	}
 	set each(v) {
 		if (v === untracked(this.#each)) {
@@ -49,6 +50,24 @@ var For = class {
 		});
 		return fragment;
 	}
+	/**
+	* @internal Hydrate support: adopt server-rendered range markers and
+	* pre-claimed entries instead of creating a fresh range. The first
+	* reconcile run sees matching key order and performs no DOM operations;
+	* later `each` changes reconcile against the adopted entries as usual.
+	*/
+	hydrateRange(start, end, entries, order) {
+		this.#start = start;
+		this.#end = end;
+		for (const [key, entry] of entries) this.#cache.set(key, entry);
+		this.#order = [...order];
+		effect(() => this.#reconcile());
+		onCleanup(() => {
+			for (const entry of this.#cache.values()) cleanEntry(entry);
+			this.#cache.clear();
+			this.#order = [];
+		});
+	}
 	#reconcile() {
 		const parent = this.#start.parentNode;
 		if (!parent) return;
@@ -148,5 +167,11 @@ function moveEntry(parent, entry, before) {
 	range.setEndAfter(entry.end);
 	parent.insertBefore(range.extractContents(), before);
 }
+const FOR_BRAND = Symbol.for("elements-kit.for");
+For[FOR_BRAND] = true;
+/** @internal Cross-instance-safe For check (identity or brand). */
+function isForComponent(type) {
+	return type === For || typeof type === "function" && type[FOR_BRAND] === true;
+}
 //#endregion
-export { For };
+export { For, isForComponent };

package/dist/fragment-ROPRBJQd.mjs

@@ -0,0 +1,61 @@
+import { _ as onCleanup, u as effect } from "./lib-DYypKhxk.mjs";
+import "./signals/index.mjs";
+import { a as mountChild } from "./element-D3om9yA6.mjs";
+import { n as Slot } from "./slot-Dvf30O0B.mjs";
+//#region src/jsx-runtime/fragment.ts
+/**
+* Parse an HTML string script-inertly: markup renders, `<script>` tags are
+* created but never execute (template parsing sets the "already started"
+* flag). Sanitizing the input is the caller's responsibility.
+*/
+function parseHtml(html) {
+	const template = document.createElement("template");
+	template.innerHTML = html;
+	return template.content;
+}
+/**
+* Used by the JSX transform for `<>...</>` fragments.
+*
+* Each child is routed through `mountChild`, which handles Nodes, strings,
+* numbers, arrays, and reactive getters — matching the behavior of any other
+* JSX container. `mountChild` also wires each child's cleanup via its own
+* `effectScope`, which links to the enclosing `effectScope` created by
+* `createElement(Fragment, ...)` for disposal propagation.
+*
+* **Raw HTML mode** — `<Fragment html>{markup}</Fragment>`: the child is a
+* `MaybeReactive<string>` rendered as markup inside a Slot region (comment
+* markers), so the server renderer and the hydration claim pass share the
+* region boundary. Reactive sources re-render the region on change. This is
+* the library's only raw-HTML sink: the string is NOT escaped — sanitize
+* untrusted input at the call site. `<script>` tags never execute.
+*/
+function Fragment(props) {
+	const fragment = document.createDocumentFragment();
+	if ("html" in props && props.html) {
+		const slot = new Slot();
+		fragment.appendChild(slot.render());
+		const source = props.children;
+		if (typeof source === "function") {
+			effect(() => {
+				const value = source();
+				slot.set(parseHtml(value == null ? "" : String(value)));
+			});
+			onCleanup(() => slot.clear());
+		} else if (source != null) slot.set(parseHtml(String(source)));
+		return fragment;
+	}
+	const children = props.children;
+	const raw = typeof children === "function" ? children() : children;
+	if (raw == null) return fragment;
+	const nodes = Array.isArray(raw) ? raw.flat(Infinity) : [raw];
+	for (const child of nodes) mountChild(fragment, child);
+	return fragment;
+}
+const FRAGMENT_BRAND = Symbol.for("elements-kit.fragment");
+Fragment[FRAGMENT_BRAND] = true;
+/** @internal Cross-instance-safe Fragment check (identity or brand). */
+function isFragmentComponent(type) {
+	return type === Fragment || typeof type === "function" && type[FRAGMENT_BRAND] === true;
+}
+//#endregion
+export { isFragmentComponent as n, parseHtml as r, Fragment as t };

package/dist/hydrate/index.d.mts

@@ -0,0 +1,41 @@
+//#region src/hydrate/claim.d.ts
+interface MismatchInfo {
+  expected: string;
+  found: Node | null;
+}
+type OnMismatch = (info: MismatchInfo) => void;
+//#endregion
+//#region src/hydrate/index.d.ts
+interface HydrateOptions {
+  /**
+   * Called when the server DOM does not match the component tree. The
+   * mismatched subtree is discarded and rendered fresh; the caller owns
+   * logging/reporting.
+   */
+  onMismatch?: OnMismatch;
+}
+interface HydrateResult {
+  /** Tear down every effect, handler and live binding wired by hydration. */
+  dispose: () => void;
+}
+/**
+ * Make server-rendered HTML interactive by re-executing the component tree
+ * in claim mode: existing DOM nodes are adopted instead of rebuilt, `on:`
+ * handlers attach to the claimed nodes, and dynamic children bind live to
+ * the server-emitted slot markers.
+ *
+ * The component code runs once on the client (closures are recreated by
+ * re-execution — no serialized handlers). Async children keep their
+ * server-rendered content visible until the client-side value settles.
+ *
+ * Server/client trees must match; on mismatch the affected subtree is
+ * rendered fresh and `options.onMismatch` is invoked.
+ *
+ * @example
+ * ```tsx
+ * const { dispose } = hydrate(document.getElementById("app")!, () => <App />);
+ * ```
+ */
+declare function hydrate(container: Element, app: () => unknown, options?: HydrateOptions): HydrateResult;
+//#endregion
+export { HydrateOptions, HydrateResult, type MismatchInfo, type OnMismatch, hydrate };

package/dist/hydrate/index.mjs

@@ -0,0 +1,2 @@
+import { t as hydrate } from "../hydrate-6Qx4n4Su.mjs";
+export { hydrate };