elements-kit 0.0.16 → 0.0.18

package/README.md

@@ -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`, `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) |
 
@@ -204,6 +207,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;
@@ -219,7 +223,7 @@ class Counter {
   }
 }
 
-document.getElementById("app")!.appendChild(new Counter().render());
+const unmount = render(document.getElementById("app")!, () => <Counter/>);
 ```
 
 ---
@@ -228,9 +232,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 +248,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,
-    );
+      </section>
+    ));
+  }
+
+  disconnectedCallback() {
+    this.#unmount?.();
+    this.#unmount = undefined;
   }
 }
 
@@ -258,6 +270,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/writing-ui/types.mdx) for the full set of prop-inference helpers.
+
 ---
 
 ## React Integration
@@ -408,7 +440,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 +459,33 @@ 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/writing-ui/types.mdx](docs/src/content/docs/writing-ui/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>` | Wrap every prop in `MaybeReactive` |
+| `MaybeReactive<T>` | Scalar value-or-getter (from `elements-kit/signals`) |
+| `Require<P, K>` | Promote optional keys to required |
+
+Function components pair `MaybeReactiveProps<P>` on the signature with `resolveProps` at the top of the body — each key becomes a callable getter, subscribing to updates on read:
+
+```tsx
+import { resolveProps } from "elements-kit/signals";
+import type { MaybeReactiveProps } from "elements-kit/jsx-runtime";
+
+function Greeting(raw: MaybeReactiveProps<{ name: string }>) {
+  const props = resolveProps(raw);
+  return <p>Hello, {props.name}</p>;
+}
+```
+
+---
+
 ## `@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` / `onCommit`
+```
+
 ---
 
 ## 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "elements-kit",
   "type": "module",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "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",
@@ -18,7 +18,7 @@
   "author": "@waelbettayeb",
   "license": "MIT",
   "main": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
+  "types": "./dist/index.d.mts",
   "files": [
     "dist"
   ],
@@ -26,52 +26,57 @@
     ".": {
       "source": "./src/index.ts",
       "import": "./dist/index.mjs",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.mts"
     },
     "./signals": {
       "source": "./src/signals/index.ts",
       "import": "./dist/signals/index.mjs",
-      "types": "./dist/signals/index.d.ts"
+      "types": "./dist/signals/index.d.mts"
     },
     "./slot": {
       "source": "./src/slot.ts",
       "import": "./dist/slot.mjs",
-      "types": "./dist/slot.d.ts"
+      "types": "./dist/slot.d.mts"
     },
     "./for": {
       "source": "./src/for.ts",
       "import": "./dist/for.mjs",
-      "types": "./dist/for.d.ts"
+      "types": "./dist/for.d.mts"
     },
     "./attributes": {
       "source": "./src/attributes.ts",
       "import": "./dist/attributes.mjs",
-      "types": "./dist/attributes.d.ts"
+      "types": "./dist/attributes.d.mts"
     },
     "./custom-elements": {
       "source": "./src/custom-elements.ts",
       "import": "./dist/custom-elements.mjs",
-      "types": "./dist/custom-elements.d.ts"
+      "types": "./dist/custom-elements.d.mts"
+    },
+    "./render": {
+      "source": "./src/render.ts",
+      "import": "./dist/render.mjs",
+      "types": "./dist/render.d.mts"
     },
     "./jsx-runtime": {
       "source": "./src/jsx-runtime/index.ts",
       "import": "./dist/jsx-runtime/index.mjs",
-      "types": "./dist/jsx-runtime/index.d.ts"
+      "types": "./dist/jsx-runtime/index.d.mts"
     },
     "./jsx-dev-runtime": {
       "source": "./src/jsx-runtime/index.ts",
       "import": "./dist/jsx-runtime/index.mjs",
-      "types": "./dist/jsx-runtime/index.d.ts"
+      "types": "./dist/jsx-runtime/index.d.mts"
     },
     "./integrations/*": {
       "source": "./src/integrations/*.ts",
       "import": "./dist/integrations/*.mjs",
-      "types": "./dist/integrations/*.d.ts"
+      "types": "./dist/integrations/*.d.mts"
     },
     "./utilities/*": {
       "source": "./src/utilities/*.ts",
       "import": "./dist/utilities/*.mjs",
-      "types": "./dist/utilities/*.d.ts"
+      "types": "./dist/utilities/*.d.mts"
     }
   },
   "scripts": {