elements-kit 0.0.17 → 0.0.19

package/README.md

@@ -25,8 +25,8 @@ class CounterElement extends HTMLElement {
     this.appendChild(
       <section>
         <p>Count: <strong>{() => this.count}</strong> — Doubled: <strong>{this.doubled}</strong></p>
-        <button onClick={() => this.count++}>+1</button>{" "}
-        <button onClick={() => this.count--}>−1</button>
+        <button on:click={() => this.count++}>+1</button>{" "}
+        <button on:click={() => this.count--}>−1</button>
       </section> as Element,
     );
   }
@@ -43,11 +43,14 @@ Every feature is a separate subpath export — import only what you use.
 
 | Entry | Purpose |
 |-------|---------|
-| `elements-kit` | `For` and core re-exports |
-| `elements-kit/signals` | `signal`, `computed`, `effect`, `effectScope`, `batch`, `untracked`, `trigger`, `onCleanup`, `@reactive` |
-| `elements-kit/attributes` | `@attributes` decorator + `ATTRIBUTES` symbol for custom elements |
-| `elements-kit/slot` | `Slot` class — comment-marker DOM regions |
-| `elements-kit/jsx-runtime` | JSX factory (configure via `jsxImportSource`) |
+| `elements-kit` | `For` component and core re-exports |
+| `elements-kit/signals` | `signal`, `computed`, `effect`, `effectScope`, `batch`, `untracked`, `trigger`, `onCleanup`, `MaybeReactive`, `resolve`, `resolveProps`, `@reactive` |
+| `elements-kit/render` | `render(target, setup)` — mount a node with a scoped lifetime; returns `unmount` |
+| `elements-kit/attributes` | `@attributes` decorator + `ATTRIBUTES` symbol |
+| `elements-kit/slot` | `Slot`, `Slots`, `SLOTS` symbol — comment-marker DOM regions |
+| `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/integrations/react` | `useSignal`, `useScope` React bridge hooks |
 | `elements-kit/utilities/*` | Reactive browser-API utilities — see [src/utilities/README.md](src/utilities/README.md) |
 
@@ -166,7 +169,7 @@ JSX compiles directly to `document.createElement`. No virtual DOM, no diffing.
 
 ```tsx
 // This:
-const el = <button onClick={() => count(count() + 1)}>{count}</button>;
+const el = <button on:click={() => count(count() + 1)}>{count}</button>;
 
 // Is equivalent to:
 const el = document.createElement("button");
@@ -190,8 +193,7 @@ const name = signal("Alice");
 | Syntax | Effect |
 |--------|--------|
 | `{signal}` / `{() => fn()}` | Live-bound reactive child |
-| `onClick={fn}` | Event listener (camelCase → `onclick`) |
-| `on:click={fn}` | Explicit event namespace |
+| `on:click={fn}` | Event listener (case-preserving event name) |
 | `class:active={bool}` | Reactive `classList.toggle` |
 | `style:color={value}` | Reactive inline style property |
 | `prop:foo={val}` | Force property assignment (skips `setAttribute`) |
@@ -204,6 +206,7 @@ Any class with a `render()` method returning an `Element` is a component. Compon
 
 ```tsx
 import { reactive, computed } from "elements-kit/signals";
+import { render } from "elements-kit/render";
 
 class Counter {
   @reactive() count = 0;
@@ -213,13 +216,13 @@ class Counter {
     return (
       <section>
         <p>{() => this.count} × 2 = {this.doubled}</p>
-        <button onClick={() => this.count++}>+1</button>
+        <button on:click={() => this.count++}>+1</button>
       </section>
     ) as Element;
   }
 }
 
-document.getElementById("app")!.appendChild(new Counter().render());
+const unmount = render(document.getElementById("app")!, () => <Counter/>);
 ```
 
 ---
@@ -228,9 +231,10 @@ document.getElementById("app")!.appendChild(new Counter().render());
 
 ElementsKit enhances native `HTMLElement` subclasses — start with the platform, add only what you need.
 
-```ts
+```tsx
 import { reactive, computed } from "elements-kit/signals";
 import { attributes, ATTRIBUTES as attr } from "elements-kit/attributes";
+import { render } from "elements-kit/render";
 
 @attributes
 class CounterElement extends HTMLElement {
@@ -243,13 +247,20 @@ class CounterElement extends HTMLElement {
   @reactive() count = 0;
   doubled = computed(() => this.count * 2);
 
+  #unmount?: () => void;
+
   connectedCallback() {
-    this.appendChild(
+    this.#unmount = render(this, () => (
       <section>
         <p>{() => this.count} × 2 = {this.doubled}</p>
-        <button onClick={() => this.count++}>+1</button>
-      </section> as Element,
-    );
+        <button on:click={() => this.count++}>+1</button>
+      </section>
+    ));
+  }
+
+  disconnectedCallback() {
+    this.#unmount?.();
+    this.#unmount = undefined;
   }
 }
 
@@ -258,6 +269,26 @@ customElements.define("x-counter", CounterElement);
 
 `<x-counter count="5" />` — attribute bound, reactive, works in any HTML context.
 
+### Typed JSX for custom elements
+
+Register the tag and augment the `CustomElementRegistry` interface — JSX infers the full prop shape (attributes, events, slots, children) from the class itself.
+
+```ts
+import { defineElement } from "elements-kit/custom-elements";
+
+defineElement("x-counter", CounterElement);
+
+declare module "elements-kit/custom-elements" {
+  interface CustomElementRegistry {
+    "x-counter": typeof CounterElement;
+  }
+}
+
+// Now `<x-counter count={5} />` is fully typed — no hand-written `declare global` block.
+```
+
+See [Types](docs/src/content/docs/elements/types.mdx) for the full set of prop-inference helpers.
+
 ---
 
 ## React Integration
@@ -408,7 +439,7 @@ effect(() => console.log(fetchTodo.state, fetchTodo.value));
 
 ## `For` — Keyed List Rendering
 
-Reconciles a reactive array into the DOM. Each item renders once per key — no full re-renders on reorder, add, or remove.
+Reconciles a reactive array into the DOM. Each item renders once per key — no full re-renders on reorder, add, or remove. `T` is inferred from `each`.
 
 ```tsx
 import { For } from "elements-kit/for";
@@ -427,6 +458,34 @@ import { For } from "elements-kit/for";
 
 ---
 
+## Prop types
+
+Six type helpers derive JSX prop shapes from your components — no parallel `declare global` block to maintain. Full guide at [docs/src/content/docs/elements/types.mdx](docs/src/content/docs/elements/types.mdx).
+
+| Helper | For |
+| ------ | --- |
+| `ElementProps<typeof Cls>` | `HTMLElement` subclass — full surface (attrs, events, slots, children) |
+| `Props<C>` | Class instance, constructor, or function component — unified |
+| `ComponentProps<typeof Cls>` | Class components with `constructor(props: P)` |
+| `MaybeReactiveProps<P>` | Caller-facing — wrap every prop in `MaybeReactive` (what parents pass) |
+| `ReactiveProps<P>` | Component-facing — every prop becomes a `Computed<T>` getter (what function components receive) |
+| `MaybeReactive<T>` | Scalar value-or-getter (from `elements-kit/signals`) |
+| `Require<P, K>` | Promote optional keys to required |
+
+The JSX runtime auto-wraps function-component props — each key arrives as a callable getter that subscribes on read. Pair the signature with `ReactiveProps<P>` and read `props.x()`:
+
+```tsx
+import type { ReactiveProps } from "elements-kit/jsx-runtime";
+
+function Greeting(props: ReactiveProps<{ name: string }>) {
+  return <p>Hello, {props.name}</p>;
+}
+```
+
+`resolveProps` stays exported for non-JSX call sites or nested prop bags.
+
+---
+
 ## `@reactive()` Decorator
 
 Makes any class field reactive — reads subscribe, writes trigger updates.
@@ -465,6 +524,26 @@ class MyElement extends HTMLElement {
 }
 ```
 
+For typed slots, attach a `[SLOTS]` instance field — pass the key list with `as const` so TS can narrow:
+
+```ts
+import { SLOTS, Slots } from "elements-kit/slot";
+
+class Card extends HTMLElement {
+  [SLOTS] = Slots.new(["header", "footer"] as const);
+}
+// ElementProps<typeof Card> now includes `slot:header` / `slot:footer`
+```
+
+For typed events, declare a `static events` map:
+
+```ts
+class XPicker extends HTMLElement {
+  declare static events: { commit: CustomEvent<number> };
+}
+// ElementProps<typeof XPicker> now includes `on:commit`
+```
+
 ---
 
 ## Roadmap
@@ -473,4 +552,3 @@ class MyElement extends HTMLElement {
 - [ ] UI library — pre-built reactive components built on ElementsKit primitives
 - [ ] More framework integrations (Vue, Solid, Angular, …)
 - [ ] Tutorial — building a full app from scratch
-- [ ] Complete TypeScript strict-mode coverage

package/dist/attributes.d.mts

@@ -1,2 +1,2 @@
-import { a as Attributes, c as observedAttributes, i as AttributeTarget, n as AttrChangeHandler, o as attributes, r as AttributeDecorated, s as dispatchAttrChange, t as ATTRIBUTES } from "./attributes-Dtn68R1u.mjs";
+import { a as Attributes, c as observedAttributes, i as AttributeTarget, n as AttrChangeHandler, o as attributes, r as AttributeDecorated, s as dispatchAttrChange, t as ATTRIBUTES } from "./attributes-aiRoArZz.mjs";
 export { ATTRIBUTES, AttrChangeHandler, AttributeDecorated, AttributeTarget, Attributes, attributes, dispatchAttrChange, observedAttributes };

package/dist/{define-CjbTZ3VG.d.mts → custom-elements-bVYOkHKt.d.mts}

@@ -1,11 +1,11 @@
-//#region src/define.d.ts
+//#region src/custom-elements.d.ts
 /**
  * Registry of custom-element tags to their constructors.
  * Users augment this interface to add typed JSX support for their elements:
  *
  * @example
  * ```ts
- * declare module "elements-kit" {
+ * declare module "elements-kit/custom-elements" {
  *   interface CustomElementRegistry {
  *     "x-range": typeof XRange;
  *   }

package/dist/custom-elements.d.mts

@@ -1,74 +1,2 @@
-import { n as defineElement, t as CustomElementRegistry } from "./define-CjbTZ3VG.mjs";
-
-//#region src/custom-elements.d.ts
-/**
- * Runs `setup` inside a fresh `effectScope` and returns both its result and
- * the scope's dispose handle.
- *
- * Use this wherever you need to run reactive code with an explicit lifetime
- * outside the JSX element flow — most commonly inside a custom element's
- * `connectedCallback`. `onCleanup`, nested `effect`s and any other
- * scope-bound registrations made in `setup` are owned by the returned
- * `dispose`.
- *
- * `untracked` detaches the new scope from any enclosing effect so it isn't
- * torn down when that effect re-runs — its lifetime is solely the caller's
- * responsibility.
- *
- * @example
- * ```ts
- * class Clock extends HTMLElement {
- *   #dispose?: () => void;
- *
- *   connectedCallback() {
- *     const { dispose } = renderScope(() => {
- *       const id = setInterval(() => (this.textContent = String(Date.now())), 1000);
- *       onCleanup(() => clearInterval(id));
- *     });
- *     this.#dispose = dispose;
- *   }
- *
- *   disconnectedCallback() {
- *     this.#dispose?.();
- *     this.#dispose = undefined;
- *   }
- * }
- * ```
- */
-declare function renderScope<T>(setup: () => T): {
-  result: T;
-  dispose: () => void;
-};
-/**
- * Runs `setup` inside an `effectScope` tied to `el`'s connected lifetime.
- *
- * Call from `connectedCallback`. Effects, `onCleanup` registrations, and
- * reactive reads inside `setup` belong to this scope. Pair with
- * {@link disconnectedScope} from `disconnectedCallback` to dispose.
- *
- * Safe to call more than once (e.g. if the element is reconnected after
- * disconnection): the previous scope is disposed first.
- *
- * @example
- * ```ts
- * class Clock extends HTMLElement {
- *   connectedCallback() {
- *     connectedScope(this, () => {
- *       const id = setInterval(() => this.textContent = String(Date.now()), 1000);
- *       onCleanup(() => clearInterval(id));
- *     });
- *   }
- *   disconnectedCallback() {
- *     disconnectedScope(this);
- *   }
- * }
- * ```
- */
-declare function connectedScope(el: HTMLElement, setup: () => void): void;
-/**
- * Disposes the scope previously created by {@link connectedScope} for `el`.
- * No-op if there is no active scope.
- */
-declare function disconnectedScope(el: HTMLElement): void;
-//#endregion
-export { type CustomElementRegistry, connectedScope, defineElement, disconnectedScope, renderScope };
+import { n as defineElement, t as CustomElementRegistry } from "./custom-elements-bVYOkHKt.mjs";
+export { CustomElementRegistry, defineElement };

package/dist/custom-elements.mjs

@@ -1,5 +1,4 @@
-import { b as untracked, f as effectScope } from "./signals-J8dK_rA4.mjs";
-//#region src/define.ts
+//#region src/custom-elements.ts
 /**
 * Register a custom element with the browser and return its class.
 * Pair with a module augmentation of `CustomElementRegistry` to get typed JSX.
@@ -9,92 +8,4 @@ function defineElement(tag, cls, options) {
 	return cls;
 }
 //#endregion
-//#region src/custom-elements.ts
-/**
-* Runs `setup` inside a fresh `effectScope` and returns both its result and
-* the scope's dispose handle.
-*
-* Use this wherever you need to run reactive code with an explicit lifetime
-* outside the JSX element flow — most commonly inside a custom element's
-* `connectedCallback`. `onCleanup`, nested `effect`s and any other
-* scope-bound registrations made in `setup` are owned by the returned
-* `dispose`.
-*
-* `untracked` detaches the new scope from any enclosing effect so it isn't
-* torn down when that effect re-runs — its lifetime is solely the caller's
-* responsibility.
-*
-* @example
-* ```ts
-* class Clock extends HTMLElement {
-*   #dispose?: () => void;
-*
-*   connectedCallback() {
-*     const { dispose } = renderScope(() => {
-*       const id = setInterval(() => (this.textContent = String(Date.now())), 1000);
-*       onCleanup(() => clearInterval(id));
-*     });
-*     this.#dispose = dispose;
-*   }
-*
-*   disconnectedCallback() {
-*     this.#dispose?.();
-*     this.#dispose = undefined;
-*   }
-* }
-* ```
-*/
-function renderScope(setup) {
-	let result;
-	let dispose;
-	untracked(() => {
-		dispose = effectScope(() => {
-			result = setup();
-		});
-	});
-	return {
-		result,
-		dispose
-	};
-}
-const scopes = /* @__PURE__ */ new WeakMap();
-/**
-* Runs `setup` inside an `effectScope` tied to `el`'s connected lifetime.
-*
-* Call from `connectedCallback`. Effects, `onCleanup` registrations, and
-* reactive reads inside `setup` belong to this scope. Pair with
-* {@link disconnectedScope} from `disconnectedCallback` to dispose.
-*
-* Safe to call more than once (e.g. if the element is reconnected after
-* disconnection): the previous scope is disposed first.
-*
-* @example
-* ```ts
-* class Clock extends HTMLElement {
-*   connectedCallback() {
-*     connectedScope(this, () => {
-*       const id = setInterval(() => this.textContent = String(Date.now()), 1000);
-*       onCleanup(() => clearInterval(id));
-*     });
-*   }
-*   disconnectedCallback() {
-*     disconnectedScope(this);
-*   }
-* }
-* ```
-*/
-function connectedScope(el, setup) {
-	scopes.get(el)?.();
-	const { dispose } = renderScope(setup);
-	scopes.set(el, dispose);
-}
-/**
-* Disposes the scope previously created by {@link connectedScope} for `el`.
-* No-op if there is no active scope.
-*/
-function disconnectedScope(el) {
-	scopes.get(el)?.();
-	scopes.delete(el);
-}
-//#endregion
-export { connectedScope, defineElement, disconnectedScope, renderScope };
+export { defineElement };

package/dist/{element-CGVy_8TW.mjs → element-DxmInKJw.mjs}

@@ -1,5 +1,6 @@
-import { _ as onCleanup, b as untracked, d as effect, f as effectScope, t as isReactive } from "./signals-J8dK_rA4.mjs";
+import { c as effectScope, g as untracked, p as onCleanup, s as effect } from "./lib-D6duEs38.mjs";
 import "./polyfill-B1lNNcum.mjs";
+import { isReactive, resolveProps } from "./signals/index.mjs";
 import { on } from "./utilities/event-listener.mjs";
 import { i as resolveNode$1, n as Slot, r as Slots, t as SLOTS } from "./slot-Kb61AcgW.mjs";
 //#region \0rolldown/runtime.js
@@ -85,23 +86,34 @@ function applySlot(slot, value) {
 	});
 }
 function mountChildren(el, value) {
-	for (const child of ensureFlatArray(value)) {
-		if (typeof child === "function") {
-			const slot = Slot.new();
-			el.appendChild(slot());
-			effectScope(() => {
-				effect(() => slot.set(resolveChild(child())));
-				onCleanup(() => slot.clear());
-			});
-			continue;
-		}
-		const node = resolveChild(child);
-		const dispose = node[Symbol.dispose];
-		el.appendChild(node);
-		if (dispose) effectScope(() => {
-			onCleanup(dispose);
+	for (const child of ensureFlatArray(value)) mountChild(el, child);
+}
+/**
+* Mounts a single child into `el`. Reactive functions become live slots; other
+* values append as-is. Each child owns its own `effectScope` so sibling
+* `onCleanup` registrations don't overwrite each other (the signals lib
+* supports only one onCleanup per subscriber).
+*
+* Also used by `createFunctionElement` when a component returns a reactive
+* getter or primitive — keeps the component's `effectScope` alive for the
+* lifetime of the fragment it mounts into.
+*/
+function mountChild(el, child) {
+	if (typeof child === "function") {
+		const slot = Slot.new();
+		el.appendChild(slot());
+		effectScope(() => {
+			effect(() => slot.set(resolveChild(child())));
+			onCleanup(() => slot.clear());
 		});
+		return;
 	}
+	const node = resolveChild(child);
+	const dispose = node[Symbol.dispose];
+	el.appendChild(node);
+	if (dispose) effectScope(() => {
+		onCleanup(dispose);
+	});
 }
 function resolveChild(value) {
 	if (Array.isArray(value)) {
@@ -209,10 +221,10 @@ function setAttribute(el, key, value) {
 	else el.setAttribute(key, value === true ? "" : String(value));
 }
 function isEventKey(key) {
-	return key.startsWith("on:") || key.length > 2 && key.startsWith("on") && key[2] >= "A" && key[2] <= "Z";
+	return key.startsWith("on:");
 }
 function eventName(key) {
-	return key.startsWith("on:") ? key.slice(3) : key[2].toLowerCase() + key.slice(3);
+	return key.slice(3);
 }
 //#endregion
 //#region src/jsx-runtime/element.ts
@@ -229,7 +241,7 @@ function createFunctionElement(type, props, ref) {
 	let dispose;
 	untracked(() => {
 		dispose = effectScope(() => {
-			el = type(props);
+			el = type(resolveProps(props));
 			if (typeof ref === "function" && el instanceof Element) ref(el);
 		});
 	});
@@ -280,4 +292,4 @@ function attachDisposables(el, disposables) {
 	});
 }
 //#endregion
-export { disposeElement as n, createElement as t };
+export { disposeElement as n, mountChild as r, createElement as t };

package/dist/for.d.mts

@@ -1,4 +1,4 @@
-import { a as Props, o as Require } from "./infer-BfzRJoCn.mjs";
+import { i as Props, s as Require } from "./infer-Dv5Wk-7E.mjs";
 
 //#region src/for.d.ts
 type KeyFn<T> = (item: T, index: number) => string | number;

package/dist/for.mjs

@@ -1,5 +1,6 @@
-import { n as disposeElement } from "./element-CGVy_8TW.mjs";
-import { _ as onCleanup, b as untracked, d as effect, f as effectScope, v as signal, y as trigger } from "./signals-J8dK_rA4.mjs";
+import { n as disposeElement } from "./element-DxmInKJw.mjs";
+import { c as effectScope, g as untracked, h as trigger, m as signal, p as onCleanup, s as effect } from "./lib-D6duEs38.mjs";
+import "./signals/index.mjs";
 //#region src/for.ts
 var For = class {
 	constructor(_props) {}