elements-kit 0.0.19 → 0.1.0

package/README.md

@@ -1,94 +1,28 @@
-<p align="center">
-  <img src="docs/public/og.svg" alt="ElementsKit" width="600" />
-</p>
+# ElementsKit 🌱
 
-# ElementsKit
-
-**Universal reactive primitives for the web.** Signals, JSX, and custom elements that work anywhere — standalone, inside React, Vue, or any framework, or as the foundation of your own component model.
+**Universal reactive primitives for the web.** Signals, JSX, custom elements, and browser-API helpers. Import one at a time, compose them, or use any of them inside vanilla JS, React, Vue, or any framework.
 
 ```tsx
-import { signal, computed, reactive } from "elements-kit/signals";
-import { attributes, ATTRIBUTES as attr } from "elements-kit/attributes";
-
-@attributes
-class CounterElement extends HTMLElement {
-  static [attr] = {
-    count(this: CounterElement, value: string | null) {
-      this.count = Number(value ?? 0);
-    },
-  };
+import { signal, computed } from "elements-kit/signals";
+import { render } from "elements-kit/render";
+import type { ReactiveProps } from "elements-kit/jsx-runtime";
 
-  @reactive() count = 0;
-  doubled = computed(() => this.count * 2);
+function Counter(props: ReactiveProps<{ initial?: number }>) {
+  const count = signal(props.initial() ?? 0);
+  const doubled = computed(() => count() * 2);
 
-  connectedCallback() {
-    this.appendChild(
-      <section>
-        <p>Count: <strong>{() => this.count}</strong> — Doubled: <strong>{this.doubled}</strong></p>
-        <button on:click={() => this.count++}>+1</button>{" "}
-        <button on:click={() => this.count--}>−1</button>
-      </section> as Element,
-    );
-  }
+  return (
+    <section>
+      <p><strong>{count}</strong> × 2 = <strong>{doubled}</strong></p>
+      <button on:click={() => count(count() + 1)}>+1</button>{" "}
+      <button on:click={() => count(count() - 1)}>−1</button>
+    </section>
+  );
 }
 
-customElements.define("x-counter", CounterElement);
+render(document.getElementById("app")!, () => <Counter initial={0} />);
 ```
 
----
-
-## Packages
-
-Every feature is a separate subpath export — import only what you use.
-
-| Entry | Purpose |
-|-------|---------|
-| `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) |
-
-## Repository
-
-- [src/](src/) — library source ([signals](src/signals/), [jsx-runtime](src/jsx-runtime/), [utilities](src/utilities/), [integrations](src/integrations/))
-- [docs/](docs/) — Astro + Starlight documentation site
-- [example/](example/) — Vite sandbox
-- [ARCHITECTURE.md](ARCHITECTURE.md) — how the library works (reactive model, JSX, custom elements, cleanup)
-- [CONTRIBUTING.md](CONTRIBUTING.md) — quick start, quality bars, versioning, PR checklist
-- [DOCS.md](DOCS.md) — doc-authoring rules
-- [AGENTS.md](AGENTS.md) — agent navigation map
-- [src/utilities/README.md](src/utilities/README.md) — utilities catalog and dependency graph
-
----
-
-## Why ElementsKit
-
-Modern UI frameworks solve reactivity and rendering together — you adopt the whole system or none of it. ElementsKit separates the two:
-
-- **Signals** are the reactive core — fine-grained, framework-agnostic, composable with any rendering model.
-- **JSX** compiles to real `document.createElement` calls — no virtual DOM, no runtime overhead.
-- **Custom elements** are standard browser components — ElementsKit enhances them with signals and JSX without wrapping or abstracting the platform.
-
-Use one piece, or all three. Integrate with React for complex UIs. Build web components that work anywhere HTML does.
-
-### Primitives first, composable abstractions
-
-Small primitives, one job each, typed interfaces at every boundary. Abstraction is assembled, not inherited — compose upward from `signal` → `sync(fromEvent(...), ...)` → `<For>` and stop at the level your feature needs. Designed for AI agents as much as for humans: each step is verifiable on its own, and there's no framework-specific mental model to learn before writing the first line.
-
-- **No prop matrices.** No single-system components with forty flags where legal combinations aren't obvious until you read the source.
-- **No hidden coupling.** Blocks meet at their types; invariants don't leak across layers.
-- **Close to the platform.** `promise` wraps a native `Promise`. JSX compiles to `document.createElement`. Custom elements are `HTMLElement` subclasses. You already know the underlying shape.
-- **Minimal surface.** `async` has no cache, no query client, no query/mutation split. If you need those, compose them on top — don't inherit them by default.
-- **Swap, don't rewrite.** Replace one block (`throttled` → `debounced`) without touching the ones around it.
-
----
-
 ## Installation
 
 ```sh
@@ -106,7 +40,35 @@ Configure JSX in your `tsconfig.json`:
 }
 ```
 
----
+## Why ElementsKit
+
+ElementsKit is a library of reactive primitives, not a framework. Each piece is its own import, runs on its own, and composes with the others — inside React, inside a custom element, or on its own in a script.
+
+- **Compose, don't configure.** Small focused APIs — `signal`, `computed`, `on`, `fromEvent`, `async`. Combine primitives instead of maintaining an overloaded interface.
+
+- **Close to the platform.** JSX compiles to `document.createElement`. `promise` extends `Promise`. Custom elements *are* `HTMLElement`. Thin or absent abstraction layers — no virtual DOM, no proxies, no build steps.
+
+- **Predictable and explicit — no magic.** `signal/compose` are reactive; nothing else is. No heuristic dependency tracking, no hidden subscriptions.
+
+- **Designed for the AI age.** Code is cheap; maintenance still isn't. Primitives compose into higher-level blocks. Swap one block at a time instead of maintaining long lines of code.
+
+- **Bundler-friendly.** Every primitive is its own subpath — `elements-kit/signals`, `elements-kit/utilities/*`, `elements-kit/integrations/*`. Import only what you need.
+
+## Packages
+
+Every feature is a separate subpath export — import only what you use.
+
+| Entry | Purpose |
+|-------|---------|
+| `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) |
 
 ## Signals
 
@@ -161,8 +123,6 @@ export const cart = new CartStore();
 
 Stores are **framework-agnostic** — the same instance drives a custom element, a React component, and a plain effect in sync.
 
----
-
 ## JSX → DOM
 
 JSX compiles directly to `document.createElement`. No virtual DOM, no diffing.
@@ -198,8 +158,6 @@ const name = signal("Alice");
 | `style:color={value}` | Reactive inline style property |
 | `prop:foo={val}` | Force property assignment (skips `setAttribute`) |
 
----
-
 ## Class Components
 
 Any class with a `render()` method returning an `Element` is a component. Components own their state and produce elements.
@@ -225,8 +183,6 @@ class Counter {
 const unmount = render(document.getElementById("app")!, () => <Counter/>);
 ```
 
----
-
 ## Custom Elements
 
 ElementsKit enhances native `HTMLElement` subclasses — start with the platform, add only what you need.
@@ -289,8 +245,6 @@ declare module "elements-kit/custom-elements" {
 
 See [Types](docs/src/content/docs/elements/types.mdx) for the full set of prop-inference helpers.
 
----
-
 ## React Integration
 
 Connect signals and stores to React components via `useSyncExternalStore`:
@@ -315,8 +269,6 @@ function CartSummary() {
 
 The same `cart` store drives custom elements, React trees, and plain scripts — all in sync.
 
----
-
 ## Utilities
 
 Pre-built reactive wrappers around common browser APIs. Each utility lives at its own subpath (`elements-kit/utilities/<name>`) and ships as its own entry — you pay only for what you import. Full catalog in [src/utilities/README.md](src/utilities/README.md).
@@ -343,8 +295,6 @@ import { windowFocused } from "elements-kit/utilities/window-focus";
 effect(() => console.log("online:", online(), "focused:", windowFocused()));
 ```
 
----
-
 ## Async & Promise
 
 Two primitives convert imperative async work into reactive state: `promise` (minimal, any `Promise` → reactive state) and `async` (full controller with start/stop/run and optional reactive input).
@@ -435,8 +385,6 @@ const fetchTodo = async(() => {
 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. `T` is inferred from `each`.
@@ -456,8 +404,6 @@ import { For } from "elements-kit/for";
 </ul>
 ```
 
----
-
 ## 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).
@@ -484,8 +430,6 @@ function Greeting(props: ReactiveProps<{ name: string }>) {
 
 `resolveProps` stays exported for non-JSX call sites or nested prop bags.
 
----
-
 ## `@reactive()` Decorator
 
 Makes any class field reactive — reads subscribe, writes trigger updates.
@@ -503,8 +447,6 @@ class TodoApp {
 }
 ```
 
----
-
 ## `@attributes` Decorator
 
 Wires `observedAttributes` and `attributeChangedCallback` from a static map:
@@ -544,7 +486,12 @@ class XPicker extends HTMLElement {
 // ElementProps<typeof XPicker> now includes `on:commit`
 ```
 
----
+## Learn more
+
+- [Documentation site](docs/) — guides, playgrounds, reference
+- [Philosophy](docs/src/content/docs/getting-started/philosophy.mdx) — deeper reasoning behind the five principles
+- [ARCHITECTURE.md](ARCHITECTURE.md) — how the library works
+- [CONTRIBUTING.md](CONTRIBUTING.md) — build, test, PR checklist
 
 ## Roadmap
 

package/dist/{attributes-aiRoArZz.d.mts → attributes-DILeh3-s.d.mts}

@@ -1,7 +1,28 @@
 //#region src/attributes.d.ts
+/**
+ * Handler signature for a single observed attribute.
+ *
+ * `this` is bound to the element instance, letting the handler assign
+ * directly to reactive properties. `value` is the raw HTML string (or `null`
+ * when the attribute is removed) — conversion to typed JS is the handler's job.
+ */
 interface AttrChangeHandler<T> {
   (this: T, value: string | null, oldValue?: string | null): void;
 }
+/**
+ * Static-field key used by the `@attributes` decorator (and
+ * {@link dispatchAttrChange} / {@link observedAttributes}) to locate the
+ * attribute handler map on a custom-element class.
+ *
+ * @example
+ * ```ts
+ * class MyElement extends HTMLElement {
+ *   static [ATTRIBUTES]: Attributes<MyElement> = {
+ *     name(value) { this.name = value ?? ""; },
+ *   };
+ * }
+ * ```
+ */
 declare const ATTRIBUTES: unique symbol;
 /**
  * Dispatches an attribute change to the matching handler in the static `attributes` map,
@@ -27,6 +48,10 @@ declare function dispatchAttrChange<T extends {
     [ATTRIBUTES]: Record<string, AttrChangeHandler<T>>;
   };
 }>(this: T, name: string, oldValue: string | null, newValue: string | null): void;
+/**
+ * Shape of the static `[ATTRIBUTES]` map: attribute name → handler bound to
+ * the element instance `T`.
+ */
 type Attributes<T> = Record<string, AttrChangeHandler<T>>;
 /**
  * Returns a deduplicated array of all observed attribute names for a custom element class and its ancestors.
@@ -63,6 +88,22 @@ declare function observedAttributes(cls: {
   observedAttributes?: string[];
   prototype: unknown;
 }): string[];
+/**
+ * Pre-decoration shape required by `@attributes` — a class constructor
+ * carrying a static `[ATTRIBUTES]` handler map.
+ */
+type AttributeTarget<T extends abstract new (...args: any[]) => HTMLElement> = T & {
+  [ATTRIBUTES]: Record<string, AttrChangeHandler<InstanceType<T>>>;
+};
+/**
+ * Post-decoration shape returned by `@attributes`: adds `observedAttributes`
+ * to the constructor and `attributeChangedCallback` to the prototype.
+ */
+type AttributeDecorated<T extends abstract new (...args: any[]) => HTMLElement> = T & (new (...args: any[]) => InstanceType<T> & {
+  attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+}) & {
+  observedAttributes: string[];
+};
 /**
  * A class decorator that automatically wires up `observedAttributes` and `attributeChangedCallback`
  * from a static `[ATTRIBUTES]` map.
@@ -71,7 +112,7 @@ declare function observedAttributes(cls: {
  *
  * @example
  * ```ts
- * @attributes
+ * \@attributes
  * class MyElement extends HTMLElement {
  *   static [ATTRIBUTES] = {
  *     count(this: MyElement, value: string | null) {
@@ -81,14 +122,6 @@ declare function observedAttributes(cls: {
  * }
  * ```
  */
-type AttributeTarget<T extends abstract new (...args: any[]) => HTMLElement> = T & {
-  [ATTRIBUTES]: Record<string, AttrChangeHandler<InstanceType<T>>>;
-};
-type AttributeDecorated<T extends abstract new (...args: any[]) => HTMLElement> = T & (new (...args: any[]) => InstanceType<T> & {
-  attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
-}) & {
-  observedAttributes: string[];
-};
 declare function attributes<T extends abstract new (...args: any[]) => HTMLElement>(target: AttributeTarget<T>, context: ClassDecoratorContext<T>): AttributeDecorated<T>;
 //#endregion
 export { Attributes as a, observedAttributes as c, AttributeTarget as i, AttrChangeHandler as n, attributes as o, AttributeDecorated as r, dispatchAttrChange as s, ATTRIBUTES as t };

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-aiRoArZz.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-DILeh3-s.mjs";
 export { ATTRIBUTES, AttrChangeHandler, AttributeDecorated, AttributeTarget, Attributes, attributes, dispatchAttrChange, observedAttributes };

package/dist/attributes.mjs

@@ -1,4 +1,18 @@
 //#region src/attributes.ts
+/**
+* Static-field key used by the `@attributes` decorator (and
+* {@link dispatchAttrChange} / {@link observedAttributes}) to locate the
+* attribute handler map on a custom-element class.
+*
+* @example
+* ```ts
+* class MyElement extends HTMLElement {
+*   static [ATTRIBUTES]: Attributes<MyElement> = {
+*     name(value) { this.name = value ?? ""; },
+*   };
+* }
+* ```
+*/
 const ATTRIBUTES = Symbol("attributes");
 /**
 * Dispatches an attribute change to the matching handler in the static `attributes` map,
@@ -68,6 +82,24 @@ function observedAttributes(cls) {
 	}
 	return Array.from(s);
 }
+/**
+* A class decorator that automatically wires up `observedAttributes` and `attributeChangedCallback`
+* from a static `[ATTRIBUTES]` map.
+*
+* The `this` type inside attribute handlers is automatically inferred from the decorated class.
+*
+* @example
+* ```ts
+* \@attributes
+* class MyElement extends HTMLElement {
+*   static [ATTRIBUTES] = {
+*     count(this: MyElement, value: string | null) {
+*       this.count = Number(value);
+*     },
+*   };
+* }
+* ```
+*/
 function attributes(target, context) {
 	context.addInitializer(function() {
 		target.observedAttributes = observedAttributes(target);

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

@@ -17,6 +17,24 @@ type AnyCtor = CustomElementConstructor;
 /**
  * Register a custom element with the browser and return its class.
  * Pair with a module augmentation of `CustomElementRegistry` to get typed JSX.
+ *
+ * @example
+ * ```tsx
+ * import { defineElement } from "elements-kit/custom-elements";
+ *
+ * class XCounter extends HTMLElement {}
+ *
+ * defineElement("x-counter", XCounter);
+ *
+ * declare module "elements-kit/custom-elements" {
+ *   interface CustomElementRegistry {
+ *     "x-counter": typeof XCounter;
+ *   }
+ * }
+ *
+ * // JSX now gets typed props + typed ref
+ * // <x-counter />
+ * ```
  */
 declare function defineElement<Tag extends `${string}-${string}`, C extends AnyCtor>(tag: Tag, cls: C, options?: ElementDefinitionOptions): C;
 //#endregion

package/dist/custom-elements.d.mts

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

package/dist/custom-elements.mjs

@@ -2,6 +2,24 @@
 /**
 * Register a custom element with the browser and return its class.
 * Pair with a module augmentation of `CustomElementRegistry` to get typed JSX.
+*
+* @example
+* ```tsx
+* import { defineElement } from "elements-kit/custom-elements";
+*
+* class XCounter extends HTMLElement {}
+*
+* defineElement("x-counter", XCounter);
+*
+* declare module "elements-kit/custom-elements" {
+*   interface CustomElementRegistry {
+*     "x-counter": typeof XCounter;
+*   }
+* }
+*
+* // JSX now gets typed props + typed ref
+* // <x-counter />
+* ```
 */
 function defineElement(tag, cls, options) {
 	customElements.define(tag, cls, options);

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

@@ -2,7 +2,7 @@ import { c as effectScope, g as untracked, p as onCleanup, s as effect } from ".
 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";
+import { i as resolveNode$1, n as Slot, r as Slots, t as SLOTS } from "./slot-CKtUoy2X.mjs";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;

package/dist/for.d.mts

@@ -1,4 +1,4 @@
-import { i as Props, s as Require } from "./infer-Dv5Wk-7E.mjs";
+import { i as Props, s as Require } from "./infer-DuFY-y2b.mjs";
 
 //#region src/for.d.ts
 type KeyFn<T> = (item: T, index: number) => string | number;
@@ -30,8 +30,37 @@ type RenderFn<T> = (item: T, index: number) => Element | DocumentFragment | null
  * Props for `<For>`, derived from its public instance fields.
  * All props are optional — the class initializes sane defaults at runtime.
  * Non-function props also accept a reactive getter.
+ *
+ * @example
+ * ```tsx
+ * import { signal } from "elements-kit/signals";
+ * import { For } from "elements-kit";
+ *
+ * const todos = signal([{ id: 1, text: "write docs" }]);
+ *
+ * const props: ForProps<{ id: number; text: string }> = {
+ *   each: todos,
+ *   by: (t) => t.id,
+ *   children: (t) => <li>{t.text}</li>,
+ * };
+ * ```
  */
 type ForProps<T> = Require<Props<For<T>>, "each" | "children">;
+/**
+ * Keyed list renderer. See {@link ForProps} for prop details.
+ *
+ * @example
+ * ```tsx
+ * import { signal } from "elements-kit/signals";
+ * import { For } from "elements-kit";
+ *
+ * const todos = signal([{ id: 1, text: "write docs" }]);
+ *
+ * <For each={todos} by={(t) => t.id}>
+ *   {(t) => <li>{t.text}</li>}
+ * </For>
+ * ```
+ */
 declare class For<T = unknown> {
   #private;
   constructor(_props?: ForProps<T>);
@@ -42,4 +71,4 @@ declare class For<T = unknown> {
   render(): DocumentFragment;
 }
 //#endregion
-export { For, ForProps };
+export { For };

package/dist/for.mjs

@@ -1,7 +1,22 @@
-import { n as disposeElement } from "./element-DxmInKJw.mjs";
+import { n as disposeElement } from "./element-w1GCIMVp.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
+/**
+* Keyed list renderer. See {@link ForProps} for prop details.
+*
+* @example
+* ```tsx
+* import { signal } from "elements-kit/signals";
+* import { For } from "elements-kit";
+*
+* const todos = signal([{ id: 1, text: "write docs" }]);
+*
+* <For each={todos} by={(t) => t.id}>
+*   {(t) => <li>{t.text}</li>}
+* </For>
+* ```
+*/
 var For = class {
 	constructor(_props) {}
 	#each = signal([]);