@deijose/nix-js 0.1.2 → 0.1.4

package/README.md

@@ -1,1032 +1,135 @@
 # ❄️ Nix.js
 
-> A lightweight, fully reactive micro-framework for building modern web UIs — no virtual DOM, no compiler, no build-time magic. Just signals, tagged templates, and pure TypeScript.
+A lightweight, fully reactive micro-framework for building modern web UIs — no virtual DOM, no compiler, no build-time magic. Just signals, tagged templates, and pure TypeScript.
 
-```
-~28 KB source · zero dependencies · TypeScript-first · ES2022
-```
-
----
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Installation & Setup](#installation--setup)
-- [Core Concepts](#core-concepts)
-- [Reactivity](#reactivity)
-  - [signal](#signal)
-  - [computed](#computed)
-  - [effect](#effect)
-  - [batch](#batch)
-  - [watch](#watch)
-  - [untrack](#untrack)
-  - [nextTick](#nexttick)
-- [Templates](#templates)
-  - [html tag](#html-tag)
-  - [Text bindings](#text-bindings)
-  - [Attribute bindings](#attribute-bindings)
-  - [Event bindings & modifiers](#event-bindings--modifiers)
-  - [Conditional rendering](#conditional-rendering)
-  - [List rendering](#list-rendering)
-  - [Keyed lists: repeat()](#keyed-lists-repeat)
-  - [DOM refs: ref()](#dom-refs-ref)
-- [Components](#components)
-  - [Function components](#function-components)
-  - [Class components: NixComponent](#class-components-nixcomponent)
-  - [Lifecycle hooks](#lifecycle-hooks)
-  - [mount()](#mount)
-- [Dependency Injection](#dependency-injection)
-  - [provide / inject](#provide--inject)
-  - [createInjectionKey](#createinjectionkey)
-- [Global Stores](#global-stores)
-  - [createStore](#createstore)
-- [Router](#router)
-  - [createRouter](#createrouter)
-  - [RouterView](#routerview)
-  - [Link](#link)
-  - [useRouter](#userouter)
-  - [Nested routes](#nested-routes)
-  - [Query parameters](#query-parameters)
-- [Async & Lazy Loading](#async--lazy-loading)
-  - [suspend()](#suspend)
-  - [lazy()](#lazy)
-- [API Reference](#api-reference)
-- [Known Limitations](#known-limitations)
-
----
-
-## Overview
-
-Nix.js is a signal-based reactive micro-framework. Its design goals are:
-
-- **No virtual DOM.** Bindings update individual DOM nodes directly via `effect()`.
-- **No compiler.** Templates are standard JavaScript tagged template literals.
-- **Fine-grained reactivity.** Only the exact text nodes and attributes that depend on a changed signal are updated — no diffing of full component trees.
-- **Zero runtime dependencies.** The entire framework is ~28 KB of TypeScript source with no `node_modules` at runtime.
-- **TypeScript-first.** Every public API is fully typed, including typed injection keys and typed store signals.
-
-### Architecture at a glance
+The `@deijose/nix-js` package provides everything you need to build reactive UIs: signals, template engine, components, stores, router, and dependency injection in a single zero-dependency bundle.
 
 ```
-signal() ──── effect() ──────────────────────────────────┐
-                │                                         │
-              html``                                      │
-                │               ┌─ text node              │
-                └── binding ────┤─ attribute  (reactive) ─┘
-                                └─ child node
+~14 KB minified · zero dependencies · TypeScript-first · ES2022
 ```
 
-Each interpolation inside `html`` creates at most one `effect()`. When a signal changes, only the DOM nodes bound to that signal are updated.
-
----
-
-## Installation & Setup
-
-Nix.js uses [Vite](https://vitejs.dev/) as its dev server and bundler.
+## Installation
 
 ```bash
-# Install as a dependency
 npm install @deijose/nix-js
 # or
 bun add @deijose/nix-js
 ```
 
-```typescript
-import { signal, html, NixComponent, mount } from "@deijose/nix-js";
-```
-
-### Development (from source)
-
-# Start development server
-npm run dev   # or: bun dev
-
-# Type check
-npx tsc --noEmit
-
-# Production build
-npm run build
-```
-
-### Project structure
-
-```
-src/
-  nix/
-    reactivity.ts   — signal, effect, computed, batch, watch, untrack, nextTick
-    template.ts     — html``, repeat(), ref()
-    lifecycle.ts    — NixComponent base class
-    component.ts    — mount()
-    store.ts        — createStore()
-    router.ts       — createRouter(), RouterView, Link, useRouter()
-    async.ts        — suspend(), lazy()
-    context.ts      — provide(), inject(), createInjectionKey()
-    index.ts        — re-exports everything
-  main.ts           — application entry point
-index.html
-```
-
-Import everything from the single entry point:
-
-```typescript
-import {
-  signal, computed, effect, batch, watch, untrack, nextTick,
-  html, repeat, ref,
-  NixComponent, mount,
-  createStore,
-  createRouter, RouterView, Link, useRouter,
-  suspend, lazy,
-  provide, inject, createInjectionKey,
-} from "./nix";
-```
-
----
-
-## Core Concepts
-
-Nix.js is built around three primitives:
-
-| Primitive | Role |
-|-----------|------|
-| `signal(v)` | A reactive value. Reading it inside an `effect` creates a subscription. |
-| `effect(fn)` | A function that re-runs whenever any signal it read changes. |
-| `html\`\`` | A tagged template that turns an HTML string + bindings into a live DOM fragment. |
-
-Everything else — `computed`, `watch`, `repeat`, `NixComponent`, `createStore`, the router, `provide`/`inject` — is built on top of these three primitives.
-
----
-
-## Reactivity
-
-### `signal`
-
-Creates a reactive container for a single value.
-
-```typescript
-const count = signal(0);
-
-count.value;              // get — 0
-count.value = 1;          // set — notifies subscribers
-count.update(n => n + 1); // set via updater function
-count.peek();             // get WITHOUT subscribing (no tracking)
-count.dispose();          // remove all subscribers
-```
-
-Signals use `Object.is` equality — setting the same value does nothing.
-
-### `computed`
-
-A derived signal whose value is recalculated automatically when its dependencies change.
-
-```typescript
-const price  = signal(10);
-const qty    = signal(3);
-const total  = computed(() => price.value * qty.value);
-
-console.log(total.value); // 30
-
-price.value = 20;
-console.log(total.value); // 60 — updated automatically
-```
-
-`computed` returns a `Signal<T>`, so it has `.value`, `.peek()`, etc.
-
-### `effect`
-
-Runs a function immediately and re-runs it whenever any signal read inside it changes. Returns a `dispose` function to stop the effect.
-
-```typescript
-const name = signal("Alice");
-
-const dispose = effect(() => {
-  document.title = `Hello, ${name.value}`;
-  // optional — return a cleanup function:
-  return () => console.log("effect cleaned up");
-});
-
-name.value = "Bob"; // re-runs the effect → document.title = "Hello, Bob"
-
-dispose(); // stops the effect
-```
-
-Effects are **self-cleaning**: before each re-run, the previous cleanup (if any) is called and all old subscriptions are dropped. This prevents stale subscriptions to signals that are no longer read.
-
-### `batch`
-
-Groups multiple signal writes into a single effect flush. Without `batch`, each write triggers its effects individually.
-
-```typescript
-const x = signal(0);
-const y = signal(0);
-
-effect(() => console.log(x.value + y.value));
-
-// Without batch: effect runs twice
-x.value = 1;
-y.value = 2;
-
-// With batch: effect runs once, at the end
-batch(() => {
-  x.value = 10;
-  y.value = 20;
-});
-```
-
-### `watch`
-
-Watches a reactive source and calls a callback with `(newValue, oldValue)` when it changes. Unlike `effect`, it does **not** run on initialization by default.
-
-```typescript
-const count = signal(0);
-
-const stop = watch(count, (newVal, oldVal) => {
-  console.log(`${oldVal} → ${newVal}`);
-});
-
-count.value = 1; // logs: "0 → 1"
-
-stop(); // stop watching
-```
-
-**Options:**
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `immediate` | `boolean` | `false` | Run callback immediately with the current value |
-| `once` | `boolean` | `false` | Auto-dispose after the first callback invocation |
-
-```typescript
-// Watch a computed expression
-watch(
-  () => user.value.role,
-  (role) => console.log("Role changed:", role),
-  { immediate: true }
-);
-
-// One-shot watcher
-watch(
-  isReady,
-  () => initApp(),
-  { once: true }
-);
-```
-
-### `untrack`
-
-Reads signals inside `fn` without creating subscriptions. Useful when you need a value but don't want the current `effect` to re-run when that signal changes.
-
-```typescript
-const a = signal(1);
-const b = signal(2);
-
-effect(() => {
-  const aVal = a.value;                   // subscribed — effect re-runs when a changes
-  const bVal = untrack(() => b.value);    // NOT subscribed — b changes won't trigger this
-  console.log(aVal + bVal);
-});
-```
-
-### `nextTick`
-
-Returns a `Promise<void>` that resolves after the current synchronous effect queue has flushed. Use it to read the DOM after a reactive change.
-
-```typescript
-const text = signal("hello");
-
-text.value = "world";
-await nextTick();
-console.log(document.querySelector("#el")?.textContent); // "world"
-
-// Callback variant:
-await nextTick(() => inputRef.el?.focus());
-```
-
----
-
-## Templates
-
-### `html` tag
-
-`html` is a tagged template literal that returns a `NixTemplate`. It parses the HTML once and creates a `DocumentFragment` with live bindings.
-
-```typescript
-import { html, signal, mount } from "./nix";
-
-const name = signal("world");
-const tpl  = html`<h1>Hello, ${() => name.value}!</h1>`;
-
-mount(tpl, "#app");
-name.value = "Nix"; // DOM updates automatically
-```
-
-### Text bindings
-
-| Syntax | Behavior |
-|--------|----------|
-| `${value}` | Static — inserted once as a text node |
-| `${() => expr}` | Reactive — updates the text node whenever signals inside change |
-
-```typescript
-const count = signal(0);
-
-html`
-  <p>Static: ${"hello"}</p>
-  <p>Reactive: ${() => count.value}</p>
-  <p>Expression: ${() => count.value > 0 ? "positive" : "zero or negative"}</p>
-`
-```
-
-### Attribute bindings
-
-```typescript
-const active  = signal(true);
-const label   = signal("Submit");
-const classes = signal("btn btn-primary");
-
-html`
-  <button
-    class=${classes}
-    disabled=${() => !active.value}
-    aria-label=${() => label.value}
-  >Submit</button>
-`
-```
-
-- Static value → set once.
-- `() => value` → reactive, updates via `effect`.
-- `null`, `undefined`, or `false` → attribute is **removed**.
-
-> **Important:** Each attribute binding must be a single interpolation that covers the entire value. Partial interpolation inside a string is not supported:
->
-> ```typescript
-> // ✅ Correct — the whole value is one interpolation
-> html`<div class=${() => `item ${active.value ? "active" : ""}`}>`
->
-> // ❌ Incorrect — mixing a literal prefix with an interpolation
-> html`<div class="item ${() => active.value ? 'active' : ''}">`
-> ```
-
-### Event bindings & modifiers
-
-Events are bound with `@eventname=`:
-
-```typescript
-const count = signal(0);
-
-html`
-  <button @click=${() => count.value++}>Increment</button>
-  <input  @input=${(e: Event) => console.log((e.target as HTMLInputElement).value)} />
-`
-```
-
-**Modifiers** are chained after the event name with `.`:
-
-| Modifier | Effect |
-|----------|--------|
-| `.prevent` | `e.preventDefault()` |
-| `.stop` | `e.stopPropagation()` |
-| `.once` | Listener removed after first call |
-| `.capture` | `useCapture = true` |
-| `.passive` | `passive: true` (performance hint) |
-| `.self` | Handler runs only when `e.target === e.currentTarget` |
-| `.enter` | Only fires when `Enter` key is pressed |
-| `.escape` | Only fires on `Escape` |
-| `.space` | Only fires on Space |
-| `.tab`, `.delete`, `.backspace` | Corresponding keys |
-| `.up`, `.down`, `.left`, `.right` | Arrow keys |
-| `.a`–`.z`, `.0`–`.9` | Single character key filter |
-
-```typescript
-html`
-  <form @submit.prevent=${handleSubmit}>
-    <input @keydown.enter=${submitOnEnter} />
-    <button @click.stop.once=${doOnce}>Once</button>
-  </form>
-`
-```
-
-### Conditional rendering
-
-Return a `NixTemplate` or `null`/`false` from a function binding:
-
-```typescript
-const show = signal(true);
-
-html`
-  <div>
-    ${() => show.value
-      ? html`<p>Visible content</p>`
-      : null
-    }
-  </div>
-`
-```
-
-When the condition changes, the previous DOM is fully cleaned up (effects disposed, `onUnmount` called) and the new branch is rendered.
-
-### List rendering
-
-For simple, stable lists:
-
-```typescript
-const items = ["Apple", "Banana", "Cherry"];
-
-html`
-  <ul>
-    ${items.map(item => html`<li>${item}</li>`)}
-  </ul>
-`
-```
-
-For reactive lists that change over time, prefer `repeat()`.
-
-### Keyed lists: `repeat()`
-
-`repeat()` enables efficient diffing: DOM nodes for unchanged keys are preserved and **only** added, removed, or reordered items are touched.
-
-```typescript
-import { repeat } from "./nix";
-
-const todos = signal([
-  { id: 1, text: "Buy milk" },
-  { id: 2, text: "Write docs" },
-]);
-
-html`
-  <ul>
-    ${() => repeat(
-      todos.value,
-      todo => todo.id,               // key function — must be unique
-      todo => html`<li>${todo.text}</li>`
-    )}
-  </ul>
-`
-```
-
-**Signature:**
-```typescript
-function repeat<T>(
-  items: T[],
-  keyFn: (item: T, index: number) => string | number,
-  renderFn: (item: T, index: number) => NixTemplate | NixComponent
-): KeyedList<T>
-```
-
-### DOM refs: `ref()`
-
-`ref()` creates a typed container that is filled with the actual DOM element after mount, and cleared on unmount.
+## Usage
 
 ```typescript
-import { ref } from "./nix";
-
-const inputRef = ref<HTMLInputElement>();
-
-const tpl = html`<input ref=${inputRef} type="text" />`;
-
-mount(tpl, "#app");
-
-// inputRef.el is now the <input> element
-inputRef.el?.focus();
-inputRef.el?.value; // ""
-```
-
-The `NixRef<T>` type:
-
-```typescript
-interface NixRef<T extends Element = Element> {
-  el: T | null;
-}
-```
-
----
-
-## Components
-
-### Function components
-
-The simplest form: a plain function that returns a `NixTemplate`. Signals inside close over the component's scope.
-
-```typescript
-import { html, signal, mount } from "./nix";
+import { signal, html, mount } from "@deijose/nix-js";
 
 function Counter() {
   const count = signal(0);
+
   return html`
     <div>
-      <p>${() => count.value}</p>
-      <button @click=${() => count.value++}>+</button>
+      <h1>${() => count.value}</h1>
+      <button @click=${() => count.value++}>Increment</button>
     </div>
   `;
 }
 
-mount(Counter(), "#app");
+mount(Counter, document.getElementById("app")!);
 ```
 
-### Class components: `NixComponent`
-
-For components that need lifecycle hooks, extend `NixComponent`:
+### Signals & reactivity
 
 ```typescript
-import { NixComponent, html, signal } from "./nix";
+import { signal, computed, effect, watch } from "@deijose/nix-js";
 
-class Timer extends NixComponent {
-  count = signal(0);
-  private _id = 0;
+const price = signal(10);
+const qty   = signal(3);
+const total = computed(() => price.value * qty.value);
 
-  onMount() {
-    this._id = setInterval(() => this.count.update(n => n + 1), 1000);
-    return () => clearInterval(this._id); // cleanup
-  }
+effect(() => console.log("Total:", total.value)); // logs on every change
 
-  render() {
-    return html`<span>${() => this.count.value}s</span>`;
-  }
-}
+watch(total, (next, prev) => console.log(prev, "→", next));
 
-mount(new Timer(), "#app");
+price.value = 20; // effect & watch fire automatically
 ```
 
-Use class components in templates exactly like any other value:
+### Components
 
 ```typescript
-html`<div>${new Timer()}</div>`
-```
-
-### Lifecycle hooks
+import { NixComponent, mount, html } from "@deijose/nix-js";
+import { signal } from "@deijose/nix-js";
 
-All hooks are optional:
-
-```typescript
 class MyComponent extends NixComponent {
-  // ① Called BEFORE render(), no DOM yet.
-  //    Use it to initialize derived state or call provide().
-  onInit() {
-    this.derived = computed(() => this.base.value * 2);
-    provide(MY_KEY, this.value);
-  }
-
-  // ② Must be implemented. Returns the template. Called once.
-  render(): NixTemplate {
-    return html`...`;
-  }
-
-  // ③ Called AFTER the component is inserted into the DOM.
-  //    Return a function for automatic cleanup on unmount.
-  onMount() {
-    const id = addEventListener("resize", this._onResize);
-    return () => removeEventListener("resize", this._onResize);
-  }
-
-  // ④ Called BEFORE the component is removed from the DOM.
-  onUnmount() {
-    console.log("bye!");
-  }
-
-  // ⑤ Catches errors thrown inside onInit() and onMount().
-  //    If not implemented, errors are re-thrown.
-  onError(err: unknown) {
-    console.error("Component error:", err);
-  }
-}
-```
-
-**Execution order:**
-
-```
-new MyComponent()
-       ↓
-   onInit()        ← no DOM, synchronous
-       ↓
-   render()        ← returns NixTemplate
-       ↓
-  [DOM inserted]
-       ↓
-   onMount()       ← DOM available; return value = cleanup fn
-       ↓
-  ...reactive updates...
-       ↓
-   onUnmount()     ← DOM still present
-   cleanup from onMount()
-       ↓
-  [DOM removed]
-```
-
-### `mount()`
-
-Mounts a `NixTemplate` or `NixComponent` into the DOM. Returns a handle with an `unmount()` method.
-
-```typescript
-// Function component
-const handle = mount(Counter(), "#app");
-
-// Class component
-const handle = mount(new Timer(), document.getElementById("app")!);
-
-// Unmount later
-handle.unmount(); // runs onUnmount, disposes all effects, removes DOM
-```
-
----
-
-## Dependency Injection
-
-Nix.js provides a Vue-style `provide`/`inject` system for passing data down a component tree without prop drilling.
-
-### `provide` / `inject`
-
-- `provide(key, value)` — call inside `onInit()` to make a value available to all descendant components.
-- `inject(key)` — retrieve the closest provided value for `key`, or `undefined` if none was provided.
-
-```typescript
-import { provide, inject, createInjectionKey } from "./nix";
-
-const THEME_KEY = createInjectionKey<Signal<string>>("theme");
-
-class ThemeProvider extends NixComponent {
-  theme = signal("dark");
+  private msg = signal("Hello");
 
   onInit() {
-    provide(THEME_KEY, this.theme); // make available to all descendants
+    setTimeout(() => (this.msg.value = "World"), 1000);
   }
 
   render() {
-    return html`<div>${new ThemedButton()}</div>`;
+    return html`<p>${() => this.msg.value}</p>`;
   }
 }
 
-class ThemedButton extends NixComponent {
-  theme = inject(THEME_KEY); // Signal<string> | undefined
-
-  render() {
-    const style = () =>
-      `background:${this.theme?.value === "dark" ? "#1e293b" : "#f0f9ff"}`;
-    return html`<button style=${style}>Click me</button>`;
-  }
-}
-```
-
-**Rules:**
-- `provide()` must be called inside `onInit()` (or a constructor), never at the module level.
-- `inject()` searches from the current component up through its ancestors. The **nearest** ancestor wins.
-- Calling `provide()` outside a component context throws an error.
-- Calling `inject()` outside a component context returns `undefined` silently.
-
-### `createInjectionKey`
-
-Creates a globally unique, typed symbol to use as a key. Typed keys prevent mismatches between provider and consumer.
-
-```typescript
-import type { InjectionKey } from "./nix";
-
-// Typed key — Signal<string> is the shape of the provided value
-const LOCALE_KEY: InjectionKey<Signal<string>> = createInjectionKey("locale");
-const USER_KEY:   InjectionKey<User>           = createInjectionKey("user");
-```
-
----
-
-## Global Stores
-
-### `createStore`
-
-Creates a reactive global store. Every property of the initial state becomes a `Signal`. An optional factory function adds typed actions.
-
-```typescript
-import { createStore } from "./nix";
-
-// Basic store — no actions
-const theme = createStore({ dark: true, fontSize: 16 });
-
-theme.dark.value = false;           // write
-theme.fontSize.value;               // read
-theme.$reset();                     // restore all signals to initial values
+mount(MyComponent, document.body);
 ```
 
-**With actions:**
+### Stores
 
 ```typescript
-const cart = createStore(
-  {
-    items: [] as string[],
-    total: 0,
-  },
-  (s) => ({
-    add:    (item: string) => s.items.update(arr => [...arr, item]),
-    remove: (item: string) => s.items.update(arr => arr.filter(i => i !== item)),
-    clear:  ()             => cart.$reset(),
-  })
-);
+import { createStore } from "@deijose/nix-js";
 
-cart.add("Milk");
-cart.items.value;   // ["Milk"]
-cart.clear();
-cart.items.value;   // []
-```
-
-**Types:**
+const counter = createStore({ count: 0 }, (state) => ({
+  increment() { state.count.value++; },
+  reset()     { state.count.value = 0; },
+}));
 
-```typescript
-// StoreSignals<T> — the signals object
-type StoreSignals<T> = { readonly [K in keyof T]: Signal<T[K]> };
-
-// Store<T, A> — signals + actions + $reset
-type Store<T, A> = StoreSignals<T> & A & { $reset(): void };
+counter.count.value; // reactive signal
+counter.increment();
 ```
 
----
-
-## Router
-
-A client-side History API router with dynamic parameters, query strings, nested routes, and reactive active-link styling.
-
-### `createRouter`
-
-Call once at app startup. Sets up the router singleton consumed by `RouterView`, `Link`, and `useRouter`.
+### Router
 
 ```typescript
-import { createRouter, RouterView, Link } from "./nix";
+import { createRouter, RouterView, Link, html } from "@deijose/nix-js";
 
 const router = createRouter([
-  { path: "/",        component: () => new HomePage()    },
-  { path: "/about",   component: () => new AboutPage()   },
-  { path: "/users/:id", component: () => new UserDetail() },
-  { path: "*",        component: () => new NotFound()    },
+  { path: "/",       component: Home },
+  { path: "/about",  component: About },
 ]);
-```
-
-The `Router` interface exposes:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `current` | `Signal<string>` | Active pathname (`/users/42`) |
-| `params` | `Signal<Record<string, string>>` | Dynamic route params (`{ id: "42" }`) |
-| `query` | `Signal<Record<string, string>>` | Query string params (`{ page: "2" }`) |
-| `navigate(path, query?)` | `void` | Navigate programmatically |
-| `routes` | `RouteRecord[]` | Original route tree |
-
-### `RouterView`
 
-A `NixComponent` that renders the matched component for a given depth level. Use `new RouterView()` for the root, `new RouterView(1)` for nested child routes.
-
-```typescript
-class App extends NixComponent {
-  render() {
-    return html`
-      <nav>
-        ${new Link("/", "Home")}
-        ${new Link("/about", "About")}
-      </nav>
-      ${new RouterView()}
-    `;
-  }
-}
-
-mount(new App(), "#app");
+const App = () => html`
+  <nav>
+    ${Link({ href: "/" },      "Home")}
+    ${Link({ href: "/about" }, "About")}
+  </nav>
+  ${RouterView(router)}
+`;
 ```
 
-### `Link`
-
-A reactive `<a>` tag that automatically applies active/inactive styles based on the current route.
+### Dependency injection
 
 ```typescript
-new Link("/about", "About Us")
-// <a href="/about" style="...active/inactive styles...">About Us</a>
-```
+import { provide, inject, createInjectionKey } from "@deijose/nix-js";
 
-Clicking a `Link` calls `router.navigate()` and updates the URL via `history.pushState` — no page reload.
+const ThemeKey = createInjectionKey<string>("theme");
 
-### `useRouter`
-
-Access the router singleton from anywhere — useful inside `NixComponent.render()`:
-
-```typescript
-class UserDetail extends NixComponent {
-  render() {
-    const router = useRouter();
-    return html`
-      <h1>User: ${() => router.params.value.id}</h1>
-      <p>Page: ${() => router.query.value.page ?? "1"}</p>
-    `;
-  }
+// Parent component
+function App() {
+  provide(ThemeKey, "dark");
+  return html`${ThemedCard()}`;
 }
-```
-
-### Nested routes
-
-Define `children` on a route. The parent component renders `new RouterView(1)` to slot in the child:
 
-```typescript
-createRouter([
-  {
-    path: "/dashboard",
-    component: () => new DashboardLayout(),
-    children: [
-      { path: "/stats",   component: () => new StatsPage()   },
-      { path: "/settings", component: () => new SettingsPage() },
-    ],
-  },
-]);
-
-class DashboardLayout extends NixComponent {
-  render() {
-    return html`
-      <aside>
-        ${new Link("/dashboard/stats",    "Stats")}
-        ${new Link("/dashboard/settings", "Settings")}
-      </aside>
-      <main>${new RouterView(1)}</main>  <!-- renders the child route -->
-    `;
-  }
+// Child component
+function ThemedCard() {
+  const theme = inject(ThemeKey); // "dark"
+  return html`<div class="card-${theme}">...</div>`;
 }
 ```
 
-### Query parameters
-
-```typescript
-const router = useRouter();
-
-// Navigate with query params as an object
-router.navigate("/users", { page: 2, sort: "name" });
-// URL: /users?page=2&sort=name
-
-// Or inline in the path string
-router.navigate("/users?page=2&sort=name");
-
-// Read them reactively
-html`<p>Page: ${() => router.query.value.page}</p>`
-
-// null/undefined removes the key
-router.navigate("/users", { page: null });
-// URL: /users
-```
-
----
-
-## Async & Lazy Loading
-
-### `suspend()`
-
-Runs an async function and renders different UIs depending on its state: `pending`, `resolved`, or `error`. The equivalent of `<Suspense>` in other frameworks.
-
-```typescript
-import { suspend } from "./nix";
-
-const userView = suspend(
-  () => fetch("/api/user").then(r => r.json()),
-  (user) => html`<div>${user.name}</div>`
-);
-
-mount(userView, "#app");
-```
-
-**Options:**
-
-```typescript
-suspend(
-  asyncFn,
-  renderFn,
-  {
-    // Template shown while pending (default: animated spinner)
-    fallback: html`<p>Loading…</p>`,
-
-    // Called with the error if the promise rejects
-    errorFallback: (err) => html`<p style="color:red">Error: ${String(err)}</p>`,
-
-    // If true, shows the fallback on every re-fetch.
-    // If false (default), keeps the previous content visible during refresh.
-    resetOnRefresh: false,
-  }
-)
-```
-
-### `lazy()`
-
-Wraps a dynamic `import()` for code-splitting. The module chunk is loaded once and cached; subsequent renders use the cached constructor directly.
-
-```typescript
-import { createRouter, lazy } from "./nix";
-
-createRouter([
-  { path: "/",      component: lazy(() => import("./pages/Home"))  },
-  { path: "/about", component: lazy(() => import("./pages/About")) },
-  {
-    path: "/admin",
-    component: lazy(
-      () => import("./pages/Admin"),
-      html`<p>Loading admin panel…</p>` // optional custom fallback
-    ),
-  },
-]);
-```
-
-Each page module must export its component as `export default`:
-
-```typescript
-// pages/Home.ts
-import { NixComponent, html } from "../nix";
-
-export default class HomePage extends NixComponent {
-  render() {
-    return html`<h1>Home</h1>`;
-  }
-}
-```
-
----
-
-## API Reference
-
-### Reactivity
-
-| Function | Signature | Description |
-|----------|-----------|-------------|
-| `signal` | `<T>(initial: T) → Signal<T>` | Create a reactive value |
-| `computed` | `<T>(fn: () => T) → Signal<T>` | Derived reactive value |
-| `effect` | `(fn: () => void\|cleanup) → dispose` | Run and re-run on signal changes |
-| `batch` | `(fn: () => void) → void` | Flush multiple writes as one update |
-| `watch` | `(source, cb, opts?) → dispose` | Observe a source, receive old+new values |
-| `untrack` | `<T>(fn: () => T) → T` | Read signals without subscribing |
-| `nextTick` | `(fn?: () => void) → Promise<void>` | Await next microtask (post-DOM-update) |
-
-### Signal methods
-
-| Method | Description |
-|--------|-------------|
-| `.value` (get) | Read value and subscribe if inside an effect |
-| `.value` (set) | Write and notify if changed |
-| `.update(fn)` | Write via `fn(current) → next` |
-| `.peek()` | Read without subscribing |
-| `.dispose()` | Clear all subscribers |
-
-### Templates
-
-| Export | Description |
-|--------|-------------|
-| `html\`\`` | Tagged template → `NixTemplate` |
-| `repeat(items, keyFn, renderFn)` | Keyed list with efficient diffing |
-| `ref<T>()` | Create a `NixRef<T>` for direct DOM access |
-
-### Components
-
-| Export | Description |
-|--------|-------------|
-| `NixComponent` | Abstract base class with lifecycle hooks |
-| `mount(component, container)` | Mount template or component → `{ unmount() }` |
-
-### Dependency Injection
-
-| Export | Description |
-|--------|-------------|
-| `createInjectionKey<T>(desc?)` | Create a typed, unique injection key |
-| `provide(key, value)` | Register a value (call in `onInit`) |
-| `inject(key)` | Retrieve the nearest provided value |
-| `InjectionKey<T>` | Type for typed injection keys |
-
-### Stores
-
-| Export | Description |
-|--------|-------------|
-| `createStore(state, actions?)` | Create a reactive global store |
-| `Store<T, A>` | Type of the returned store |
-| `StoreSignals<T>` | Signal-mapped type of a state shape |
-
-### Router
-
-| Export | Description |
-|--------|-------------|
-| `createRouter(routes)` | Initialize the router singleton |
-| `useRouter()` | Access the active router from anywhere |
-| `RouterView` | Component that renders the matched route |
-| `Link` | Reactive anchor component |
-| `Router` | Router instance interface |
-| `RouteRecord` | Route definition type |
-
-### Async
-
-| Export | Description |
-|--------|-------------|
-| `suspend(asyncFn, renderFn, opts?)` | Async data fetching with Suspense |
-| `lazy(importFn, fallback?)` | Dynamic import with caching |
-| `SuspenseOptions` | Options type for `suspend()` |
-
----
-
-## Known Limitations
-
-**Partial attribute interpolation is not supported.**
-
-Each dynamic attribute must be a single interpolation covering the entire attribute value. Mixing static text and expressions inside one attribute value does not work:
-
-```typescript
-// ✅ Works — the whole value is one expression
-html`<div class=${() => `item ${isActive.value ? "active" : ""}`}>`
-
-// ❌ Does NOT work — static prefix + dynamic suffix in same attribute
-html`<div class="item ${() => isActive.value ? 'active' : ''}">`
-```
+## Documentation
 
-Workaround: compute the full string outside the template and bind the result.
+For the complete API reference, guides, and all features (async/lazy, lifecycle hooks, event modifiers, keyed lists, query params, nested routes, and more):
 
----
+**→ [Full documentation on GitHub](https://github.com/deijose/nix-js)**
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deijose/nix-js",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "A lightweight, fully reactive micro-framework — no virtual DOM, no compiler, just signals and tagged templates.",
   "license": "MIT",
   "type": "module",
@@ -42,7 +42,9 @@
     "build": "tsc && vite build",
     "preview": "vite preview",
     "build:lib": "vite build --config vite.lib.config.ts && tsc --project tsconfig.lib.json && terser dist/lib/nix-js.js -c -m -o dist/lib/nix-js.js && terser dist/lib/nix-js.cjs -c -m -o dist/lib/nix-js.cjs",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "cp README.md .readme-full.md && cp .readme-npm.md README.md",
+    "postpublish": "mv .readme-full.md README.md"
   },
   "devDependencies": {
     "terser": "^5.46.0",