ilha 0.0.1 → 0.1.0

package/README.md

@@ -1,299 +1,510 @@
-# ilha
+# `ilha`
 
-A tiny, framework-free island architecture library. Define interactive islands with typed props, reactive state, async-derived data, and slots — render them as plain HTML strings on the server, mount them on the client.
+A tiny, isomorphic island framework for building reactive UI components. Runs in the browser with fine-grained signal reactivity and on the server as a synchronous HTML string renderer. Powered by [alien-signals](https://github.com/stackblitz/alien-signals) — zero virtual DOM, no compiler required.
 
-Built on [alien-signals](https://github.com/stackblitz/alien-signals) for fine-grained reactivity. Supports any [Standard Schema](https://standardschema.dev) validator (Zod, Valibot, ArkType, …).
+---
 
-## Install
+## Installation
 
 ```bash
-bun add ilha
-# or
 npm install ilha
+# or Bun
+bun add ilha
 ```
 
-## Quick start
+---
+
+## Quick Start
 
 ```ts
-import ilha, { html, mount } from "ilha";
-import { z } from "zod";
+import ilha, { html } from "ilha";
 
-const counter = ilha
-  .input(z.object({ count: z.number().default(0) }))
-  .state("count", ({ count }) => count)
-  .on("[data-inc]@click", ({ state }) => state.count(state.count() + 1))
+const Counter = ilha
+  .state("count", 0)
+  .on("button@click", ({ state }) => state.count(state.count() + 1))
   .render(
     ({ state }) => html`
-      <p>${state.count}</p>
-      <button data-inc>+</button>
+      <div>
+        <p>Count: ${state.count}</p>
+        <button>Increment</button>
+      </div>
     `,
   );
 
-// SSR — sync islands return a string immediately
-counter({ count: 5 }); // → "<p>5</p><button data-inc>+</button>"
+// SSR
+Counter.toString(); // → '<div><p>Count: 0</p><button>Increment</button></div>'
 
-// Client — mount onto a DOM element
-mount({ counter });
+// Client
+Counter.mount(document.getElementById("app"));
 ```
 
-```html
-<div data-ilha="counter" data-props='{"count": 5}'></div>
-```
+---
+
+## Core Concepts
+
+Islands are **self-contained reactive components** that know how to render themselves to an HTML string (SSR) and mount themselves into the DOM (client). You build an island using a fluent builder chain: declare inputs, state, events, effects, then call `.render()` to get a callable `Island` object.
+
+State is managed with signals — when a signal changes, only the affected island re-renders using a minimal DOM morph. No virtual DOM diffing, no framework overhead.
+
+---
 
 ## Builder API
 
-Every island is built with a chainable builder. All methods return a new builder — nothing is mutated.
+Every island starts from the `ilha` builder object (or `ilha.input()` if you need typed props).
+
+### `ilha.input(schema)`
+
+Declares the island's external input type using any [Standard Schema](https://standardschema.dev/) compatible validator (e.g. Zod, Valibot, ArkType).
+
+```ts
+import { z } from "zod";
+
+const MyIsland = ilha
+  .input(z.object({ name: z.string().default("World") }))
+  .render(({ input }) => `<p>Hello, ${input.name}!</p>`);
+
+MyIsland.toString({ name: "Ilha" }); // → '<p>Hello, Ilha!</p>'
+```
+
+Async schemas are not supported.
 
-| Method                          | Description                                                        |
-| ------------------------------- | ------------------------------------------------------------------ |
-| `.input(schema)`                | Declare typed props via any Standard Schema validator              |
-| `.state(key, init)`             | Add a reactive signal; `init` can be a value or `(input) => value` |
-| `.derived(key, fn)`             | Derive reactive data from state/input — sync or async              |
-| `.bind(selector, stateKey)`     | Two-way bind a form element to a state key                         |
-| `.on(selector@event, handler)`  | Attach a delegated event listener                                  |
-| `.effect(fn)`                   | Run a reactive side effect on mount; return a cleanup function     |
-| `.slot(name, island)`           | Nest a child island                                                |
-| `.transition({ enter, leave })` | Async-safe mount/unmount animations                                |
-| `.render(fn)`                   | Finalize — returns an `Island`                                     |
+---
 
-## Events
+### `.state(key, init?)`
 
-The `.on()` selector string uses `selector@event` syntax with optional modifiers:
+Declares a reactive state signal. The initial value can be a static value or a function receiving the resolved `input`.
 
 ```ts
-.on("[data-btn]@click", handler)                   // delegated click
-.on("@click", handler)                             // bind to root element
-.on("[data-btn]@click:once", handler)              // fires once
-.on("[data-btn]@click:passive:capture", handler)
+ilha
+  .state("count", 0)
+  .state("name", "anonymous")
+  .state("double", ({ count }) => count * 2) // init from input
+  .render(({ state }) => `<p>${state.count()}</p>`);
 ```
 
-## Two-way binding
+State accessors are **getters and setters** — call without arguments to read, call with a value to write:
 
-`.bind(selector, stateKey)` creates a two-way link between a form element and a state key — no event handler boilerplate needed:
+```ts
+state.count(); // → 0  (read)
+state.count(5); // → sets to 5 (write)
+```
+
+Inside `html\`\``, you can interpolate signal accessors directly **without calling them** — `ilha` detects signal accessors and calls them for you, also applying HTML escaping:
 
 ```ts
-const form = ilha
-  .state("email", "")
-  .state("subscribe", false)
-  .bind("[data-email]", "email")
-  .bind("[data-sub]", "subscribe")
-  .render(
-    ({ state }) => html`
-      <input data-email value="${state.email()}" />
-      <input type="checkbox" data-sub ${state.subscribe() ? "checked" : ""} />
-      <p>Email: ${state.email()}, Subscribe: ${state.subscribe()}</p>
-    `,
-  );
+html`<p>${state.count}</p>`; // same as html`<p>${state.count()}</p>`
 ```
 
-Both directions are handled automatically:
+---
 
-- **DOM → state** — when the user types or toggles, the signal updates immediately
-- **state → DOM** — when the signal changes programmatically, the element's value/checked syncs
+### `.derived(key, fn)`
 
-The DOM value is automatically coerced to match the type of the state key — no manual conversion needed:
+Declares an async (or sync) derived value. The function receives `{ state, input, signal }` where `signal` is an `AbortSignal` that aborts on re-run. Re-runs automatically when any reactive dependency changes.
 
 ```ts
-.state("count", 0)
-.bind("[data-count]", "count") // input string coerced to number automatically
+ilha
+  .state("userId", 1)
+  .derived("user", async ({ state, signal }) => {
+    const res = await fetch(`/api/users/${state.userId()}`, { signal });
+    return res.json();
+  })
+  .render(({ derived }) => {
+    if (derived.user.loading) return `<p>Loading…</p>`;
+    if (derived.user.error) return `<p>Error: ${derived.user.error.message}</p>`;
+    return `<p>${derived.user.value.name}</p>`;
+  });
 ```
 
-If the input is cleared and the state is a number, the value falls back to `0` rather than `NaN`.
+Each derived value exposes `{ loading, value, error }`.
 
-Element types and their behaviour:
+---
 
-| Element                  | Event              | Property          |
-| ------------------------ | ------------------ | ----------------- |
-| `input` (text, email, …) | `input`            | `.value`          |
-| `input[type=number]`     | `input`            | `.valueAsNumber`  |
-| `input[type=checkbox]`   | `change`           | `.checked`        |
-| `input[type=radio]`      | `change`           | selected `.value` |
-| `select`, `textarea`     | `change` / `input` | `.value`          |
+### `.on(selector, handler)`
 
-For radio groups, bind all radios in the group to the same state key, typically via a shared selector like `[name=plan]`. The state stores the selected radio's `value`:
+Attaches a delegated event listener. The selector string uses the format `"cssSelector@eventName"`. Omit the selector part to target the island host itself.
 
-`.bind()` is a no-op during SSR — it only activates on mount.
+```ts
+ilha
+  .state("count", 0)
+  .on("@click", ({ state }) => state.count(state.count() + 1)) // host click
+  .on("button.inc@click", ({ state }) => state.count(state.count() + 1)) // child click
+  .on("input@input:debounce", ({ state, event }) => {
+    // with modifier
+    state.query((event.target as HTMLInputElement).value);
+  })
+  .render(({ state }) => html`<div><button class="inc">+</button></div>`);
+```
+
+**Event modifiers** — append after a `:` separator:
+
+| Modifier  | Description              |
+| --------- | ------------------------ |
+| `once`    | Listener fires only once |
+| `capture` | Capture phase            |
+| `passive` | `{ passive: true }`      |
 
-### Stale element references
+Multiple modifiers can be combined: `@click:once:capture`.
 
-Every time bound state changes, the island re-renders and replaces `el.innerHTML`. Any element reference captured before a state change becomes stale. Always re-query from `el` after dispatching events or triggering state changes:
+The handler receives a `HandlerContext`:
 
 ```ts
-// ✗ — reference captured before re-render, may be a detached element
-const input = el.querySelector("[data-q]")!;
-input.dispatchEvent(new Event("input"));
-input.value; // stale
-
-// ✓ — always re-query after a state-changing interaction
-el.querySelector<HTMLInputElement>("[data-q]")!.dispatchEvent(new Event("input"));
-el.querySelector<HTMLInputElement>("[data-q]")!.value; // fresh
+{
+  state: IslandState; // reactive state signals
+  input: TInput; // resolved input props
+  host: Element; // island root element
+  target: Element; // element that fired the event (typed per event name)
+  event: Event; // the native event (typed per event name)
+}
 ```
 
-## Derived data
+---
+
+### `.effect(fn)`
+
+Registers a reactive effect that runs after mount and re-runs when any signal it reads changes. Optionally returns a cleanup function.
+
+```ts
+ilha
+  .state("title", "Hello")
+  .effect(({ state }) => {
+    document.title = state.title();
+    return () => {
+      document.title = "";
+    }; // cleanup on unmount or re-run
+  })
+  .render(({ state }) => `<p>${state.title()}</p>`);
+```
 
-`.derived()` computes values from state or input. It can be sync or async.
+---
 
-### Sync derived
+### `.onMount(fn)`
 
-Sync derived is a pure computation — `value` is available immediately with no loading state, and updates synchronously whenever its dependencies change:
+Runs once after the island is mounted into the DOM. Receives `{ state, derived, input, host, hydrated }` where `hydrated` is `true` when the island was mounted over existing SSR content. Optionally returns a cleanup function called on unmount.
 
 ```ts
-const island = ilha
-  .state("count", 0)
-  .derived("doubled", ({ state }) => state.count() * 2)
-  .on("[data-inc]@click", ({ state }) => state.count(state.count() + 1))
+ilha
+  .onMount(({ host, hydrated }) => {
+    console.log("mounted", hydrated ? "(hydrated)" : "(fresh)");
+    return () => console.log("unmounted");
+  })
+  .render(() => `<div>hello</div>`);
+```
+
+`.onMount()` is skipped when `snapshot.skipOnMount` is set via `.hydratable()`.
+
+---
+
+### `.bind(selector, stateKey | externalSignal)`
+
+Two-way binds a form element to a state key or an external signal. Handles `input`, `select`, `textarea`, `checkbox`, `radio`, and `number` inputs automatically.
+
+```ts
+ilha
+  .state("name", "")
+  .state("agreed", false)
+  .bind("input.name", "name")
+  .bind("input[type=checkbox]", "agreed")
   .render(
-    ({ state, derived }) => html`
-      <p>${state.count()} × 2 = ${derived.doubled.value}</p>
-      <button data-inc>+</button>
+    ({ state }) => html`
+      <form>
+        <input class="name" value="${state.name}" />
+        <input type="checkbox" />
+        <p>Hello, ${state.name}! Agreed: ${state.agreed}</p>
+      </form>
     `,
   );
 ```
 
-### Async derived
+You can also bind to an external signal created with `context()`:
+
+```ts
+.bind("input", myContextSignal)
+```
+
+---
+
+### `.slot(name, island)`
+
+Embeds a child island as a named slot. The child island is mounted and managed independently. During SSR the slot renders the child's HTML inline; during client mount the child island is activated for interactivity.
+
+```ts
+const Icon = ilha.render(() => `<svg>…</svg>`);
+
+const Card = ilha.slot("icon", Icon).render(
+  ({ slots }) => html`
+    <div class="card">
+      ${slots.icon()}
+      <p>Card content</p>
+    </div>
+  `,
+);
+```
+
+---
 
-Async derived wraps the result in a `{ loading, value, error }` envelope. Previous `value` is preserved while re-fetching (stale-while-revalidate). Each run gets an `AbortSignal` — stale requests are cancelled automatically when dependencies change:
+### `.transition(opts)`
+
+Attaches enter/leave transition callbacks called on mount and unmount respectively.
 
 ```ts
-const pokemon = ilha
-  .state("name", "charizard")
-  .derived("data", async ({ state, signal }) => {
-    const res = await fetch(`https://pokeapi.co/api/v2/pokemon/${state.name()}`, { signal });
-    return res.json() as Promise<{ name: string }>;
+ilha
+  .transition({
+    enter: async (host) => {
+      host.animate([{ opacity: 0 }, { opacity: 1 }], 300).finished;
+    },
+    leave: async (host) => {
+      await host.animate([{ opacity: 1 }, { opacity: 0 }], 300).finished;
+    },
   })
-  .render(({ derived }) => {
-    const { loading, value, error } = derived.data;
-    if (loading) return `<p>Loading${value ? ` (was: ${value.name})` : ""}…</p>`;
-    if (error) return `<p>Error: ${error.message}</p>`;
-    return `<p>${value!.name}</p>`;
-  });
+  .render(() => `<div>content</div>`);
 ```
 
-### Async SSR
+The `leave` transition is awaited before cleanup runs.
+
+---
 
-On the server, islands with async derived values can be used in two ways:
+### `.render(fn)`
 
-- **`await island()`** — resolves all async derived values before rendering final HTML
-- **`island.toString()`** or implicit template interpolation — stays synchronous and uses the loading fallback for async derived values
+Finalises the builder and returns an `Island`. The render function receives `{ state, derived, input, slots }` and must return a string or `RawHtml`.
 
 ```ts
-const page = ilha
-  .derived("user", async () => ({ name: "Ada" }))
-  .render(({ derived }) => {
-    if (derived.user.loading) return "<p>Loading…</p>";
-    if (derived.user.error) return `<p>Error: ${derived.user.error.message}</p>`;
-    return `<p>${derived.user.value!.name}</p>`;
-  });
+const MyIsland = ilha.state("x", 1).render(({ state, input }) => html`<p>${state.x}</p>`);
+```
+
+---
+
+## Island Interface
+
+Every island produced by `.render()` exposes:
+
+### `island(props?)` / `island.toString(props?)`
+
+Render the island to an HTML string synchronously. `island.toString()` is always synchronous. If `.derived()` entries have async functions, they render in `loading: true` state when called synchronously.
 
-// async SSR
-await page(); // → "<p>Ada</p>"
+Calling `island(props)` returns a `string` (or `Promise<string>` when derived values are async and awaited).
 
-// sync fallback
-page.toString(); // → "<p>Loading…</p>"
-`${page}`; // → "<p>Loading…</p>"
+```ts
+MyIsland.toString(); // always sync
+MyIsland.toString({ name: "Ilha" }); // with props
+await MyIsland({ name: "Ilha" }); // async — awaits derived
 ```
 
-This keeps SSR flexible:
+---
 
-- sync islands remain zero-overhead and return a plain string
-- async islands can be awaited when the server runtime supports async rendering
-- template literals remain safe and synchronous
+### `island.mount(host, props?)`
 
-### Derived envelope
+Mounts the island into a DOM element. Reads `data-ilha-props` and `data-ilha-state` from the host element automatically — no need to pass props when hydrating SSR output.
 
-Every `.derived()` value — sync or async — is accessed as:
+Returns an `unmount` function.
 
 ```ts
-derived.key.loading; // boolean — always false for sync
-derived.key.value; // T | undefined
-derived.key.error; // Error | undefined — always undefined for sync
+const unmount = MyIsland.mount(document.getElementById("app"));
+unmount(); // → stops effects, removes listeners, runs leave transition
 ```
 
-### Derived context
+In dev mode, double-mounting the same element logs a warning and returns a no-op.
+
+---
 
-The `fn` passed to `.derived()` receives:
+### `island.hydratable(props, options)`
+
+Async method that renders the island wrapped in a `data-ilha` hydration container. Used for SSR+hydration pipelines.
 
 ```ts
-({ state, input, signal }) => ...
-//                ^^^^^^  AbortSignal — only meaningful for async
+const html = await MyIsland.hydratable(
+  { name: "Ilha" },
+  {
+    name: "my-island", // registry key for client-side activation
+    as: "div", // wrapper tag (default: "div")
+    snapshot: true, // embed state + derived as data-ilha-state
+    skipOnMount: false, // skip onMount on hydration (default: true when snapshot)
+  },
+);
+// → '<div data-ilha="my-island" data-ilha-props="…" data-ilha-state="…">…</div>'
 ```
 
-## Slots
+**`snapshot` option:**
+
+| Value                             | Behaviour                                     |
+| --------------------------------- | --------------------------------------------- |
+| `false`                           | No snapshot — onMount always runs             |
+| `true`                            | Snapshots both state and derived values       |
+| `{ state: true, derived: false }` | Fine-grained control over what is snapshotted |
 
-Compose islands by nesting them as slots:
+---
+
+## Top-level Helpers
+
+### `ilha.mount(registry, options?)` / `mount(registry, options?)`
+
+Auto-discovers all `[data-ilha]` elements in the DOM and mounts the corresponding island from the registry.
 
 ```ts
-const app = ilha
-  .slot("counter", counter)
-  .render(
-    ({ slots }) => html`
-      <div>${slots.counter} // default props ${slots.counter({ count: 10 })} // with props</div>
-    `,
-  );
+import { mount } from "ilha";
+
+const { unmount } = mount(
+  { counter: Counter, card: Card },
+  {
+    root: document.getElementById("app"), // default: document.body
+    lazy: true, // use IntersectionObserver (mount on visibility)
+  },
+);
+
+unmount(); // → unmounts all discovered islands
 ```
 
-Or declaratively in HTML:
+---
+
+### `ilha.from(selector, island, props?)` / `from(selector, island, props?)`
+
+Mounts a single island into the first element matching `selector`. Returns the `unmount` function, or `null` if the element is not found.
+
+```ts
+import { from } from "ilha";
 
-```html
-<div data-ilha-slot="counter" data-props='{"count": 10}'></div>
+const unmount = from("#hero", HeroIsland, { title: "Welcome" });
 ```
 
-## Shared state
+---
+
+### `context(key, initial)`
 
-`context()` creates a module-level signal shared across all islands. The same key always returns the same signal — the initial value from the first registration wins.
+Creates a **global context signal** — a named reactive signal shared across all islands. Identical keys always return the same signal instance.
 
 ```ts
 import { context } from "ilha";
 
-const theme = context("theme", "light");
+const theme = context("app.theme", "light");
 
 theme(); // → "light"
-theme("dark"); // updates all subscribed islands
+theme("dark"); // → sets to "dark"
 ```
 
-> **Note:** Context signals are global for the lifetime of the page. There is no per-instance scoping or cleanup.
+Safe to call in both SSR and browser environments.
+
+---
+
+### `html\`\`` tagged template
 
-## Mounting
+XSS-safe HTML template tag. Interpolated values are HTML-escaped by default. Pass `raw()` to opt out of escaping.
 
 ```ts
-// Auto-discover all [data-ilha] elements
-mount({ counter, app });
-mount({ counter }, { root: document.querySelector("#app") });
-mount({ counter }, { lazy: true }); // IntersectionObserver
-mount({ counter }, { hydrate: true }); // preserve SSR HTML
+import { html, raw } from "ilha";
 
-// Mount a single island by selector or element
-import { from } from "ilha";
-from("#my-counter", counter, { count: 5 });
+const name = "<script>alert(1)</script>";
+html`<p>${name}</p>`; // → <p>&lt;script&gt;…</p>  (escaped)
+html`<p>${raw("<b>hi</b>")}</p>`; // → <p><b>hi</b></p>      (raw)
+```
+
+Interpolation rules:
+
+| Value type           | Behaviour                                   |
+| -------------------- | ------------------------------------------- |
+| `string` / `number`  | HTML-escaped                                |
+| `null` / `undefined` | Omitted (empty string)                      |
+| `raw(str)`           | Inserted as-is (no escaping)                |
+| `html\`…\``          | Inserted as-is (already safe)               |
+| Signal accessor      | Called and escaped                          |
+| Array                | Each item processed recursively (no commas) |
+
+**List rendering pattern:**
+
+```ts
+const items = ["apple", "banana", "cherry"];
+html`<ul>
+  ${items.map((item) => html`<li>${item}</li>`)}
+</ul>`;
 ```
 
-## SSR hydration
+---
+
+### `raw(value)`
 
-Set `data-ilha-state` on the element to restore serialised state client-side without re-running validation:
+Marks a string as trusted raw HTML, bypassing escaping when used inside `html\`\``.
 
-```html
-<div data-ilha="counter" data-ilha-state='{"count": 42}'>
-  <p>42</p>
-  <button data-inc>+</button>
-</div>
+```ts
+import { raw } from "ilha";
+
+raw("<strong>bold</strong>"); // → passes through unescaped
 ```
 
-## `html` template tag
+---
 
-Safe HTML template helper — escapes all interpolations by default:
+### `type(coerce?)`
+
+Creates a lightweight Standard Schema validator for use with `.input()` — useful when you don't want a full validation library.
 
 ```ts
-import { html, raw } from "ilha";
+import { type } from "ilha";
 
-html`<p>${userInput}</p>`; // escaped
-html`<p>${raw("<b>bold</b>")}</p>`; // explicit raw passthrough
-html`<p>${state.count}</p>`; // signal accessor — calls getter + escapes
+const MyIsland = ilha
+  .input(type((v: unknown) => v as { count: number }))
+  .render(({ input }) => `<p>${input.count}</p>`);
 ```
 
-## Known limitations
+---
+
+## SSR + Hydration
+
+The recommended SSR + hydration pattern uses `.hydratable()` on the server and `ilha.mount()` on the client.
+
+### Server
+
+```ts
+import { MyIsland } from "./islands";
+
+const html = await MyIsland.hydratable({ count: 42 }, { name: "my-island", snapshot: true });
+
+return `<!doctype html><html><body>${html}</body></html>`;
+```
+
+### Client
+
+```ts
+import { mount } from "ilha";
+import { MyIsland } from "./islands";
+
+mount({ "my-island": MyIsland });
+```
+
+The client reads `data-ilha-state` to restore signal values from the snapshot, skipping a needless re-render and calling `.onMount()` only if `skipOnMount` is not set.
+
+### State snapshot flow
+
+```
+server                                    client
+──────────────────────────────────────    ──────────────────────────────────────────
+.hydratable({ count: 42 }, {              mount({ "my-island": MyIsland })
+  name: "my-island",                        → reads data-ilha-state
+  snapshot: true                            → restores signals from snapshot
+})                                          → skips onMount (skipOnMount: true)
+→ data-ilha-state='{"count":42}'            → attaches event listeners
+                                            → starts effects + derived watchers
+```
+
+---
+
+## TypeScript
+
+Key exported types:
+
+```ts
+import type {
+  Island,
+  IslandState,
+  IslandDerived,
+  DerivedValue,
+  SlotAccessor,
+  HydratableOptions,
+  OnMountContext,
+  HandlerContext,
+  HandlerContextFor,
+  MountOptions,
+  MountResult,
+} from "ilha";
+```
 
-- `context()` signals are global with no scoping or cleanup mechanism
-- Implicit string interpolation of islands (`${island}`) is always synchronous, so async derived values fall back to `loading`
+---
 
 ## License