ilha 0.12.1 → 0.14.0

package/README.md

@@ -1,373 +1,167 @@
 # `ilha`
 
-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.
+A tiny, isomorphic UI library. You write a function component, declare `atom()` values, and render with JSX. Runs in the browser with signal reactivity and on the server as HTML. Powered by [Effect](https://effect.website) — no virtual DOM, no compiler.
 
 ---
 
 ## Installation
 
 ```bash
-npm install ilha
+npm install ilha effect
 # or Bun
-bun add ilha
+bun add ilha effect
 ```
 
----
-
-## Quick Start
-
-```ts
-import { ilha, state, action, html, mount } from "ilha";
-
-const Counter = ilha(() => {
-  const count = state(0);
-
-  const increment = action(() => {
-    count((value) => value + 1);
-  });
-
-  return html`
-    <div>
-      <p>Count: ${count()}</p>
-      <button onclick=${increment}>Increment</button>
-    </div>
-  `;
-});
-
-// SSR
-Counter.toString(); // → '<div><p>Count: 0</p><button>Increment</button></div>'
-
-// Client
-Counter.mount(document.getElementById("app"));
-```
+`effect` is a peer dependency.
 
 ---
 
-## Core Concepts
-
-Islands are **function components** that know how to render themselves to an HTML string (SSR) and mount themselves into the DOM (client). Create one by passing the component to `ilha()`.
+## Quick start
 
-An island reruns when a reactive value it reads during rendering changes. Reactive primitives — `state()`, `derived()`, `action()`, `effect()`, `effect.once()`, and `onError()` — are registered by call order and persist across rerenders. Declare them at the component's top level in a stable order.
-
-### Choose the smallest component form
+```tsx
+import { atom, mount } from "ilha";
 
-| Form                           | Ownership                                                           |
-| ------------------------------ | ------------------------------------------------------------------- |
-| `const View = () => JSX`       | The containing island owns rendering, events, and cleanup           |
-| `const View = ilha(() => JSX)` | `View` owns an independent reactive scope, lifecycle, and hydration |
+const Counter = () => {
+  const count = atom(0);
+  return (
+    <button type="button" onclick={() => count.update((n: number) => n + 1)}>
+      Count: {count}
+    </button>
+  );
+};
 
-```tsx
-const Label = ilha<{ label: string }>(({ label }) => <span>{label}</span>);
+mount(document.getElementById("app")!, Counter);
 ```
 
-A plain function component stays transparent: its rendering, events, and cleanup belong to the containing island. Wrap it with `ilha()` when it needs independent ownership.
-
-## Primitives
+A **component** is a function, async function, or generator that returns a view. Nested functions share the parent fiber. `mount` / `renderToString` on a function makes it a root.
 
-### `state(init?)`
+---
 
-Island-local reactive state. Returns a signal accessor — a function that reads or writes depending on how you call it:
+## Atoms
 
 ```tsx
-const Counter = ilha(() => {
-  const count = state(0);
-  return <p>{count()}</p>;
-});
+import { atom } from "ilha";
 
+const count = atom(0);
 count(); // read
-count(5); // write
-count((previous) => previous + 1); // update from the latest value
+count.set(1); // replace
+count.update((n) => n + 1); // patch
 ```
 
-A function argument is a lazy initializer. To store a function value, return it from an updater wrapper: `callback(() => nextCallback)`.
-
-A state initializer applies only when the instance is created. Later prop changes rerender the component but do not reset state:
+In JSX, `{count}` subscribes the render. A function initializer is a **computed** atom:
 
 ```tsx
-const Counter = ilha<{ start: number }>(({ start }) => {
-  const count = state(start);
-  return <p>{count()}</p>;
-});
-```
-
-### `derived(fn)`
-
-Compute a value from state or props. Supports synchronous values, promises, and async generators, with a built-in `{ loading, value, error }` envelope:
-
-```tsx
-const UserCard = ilha<{ userId: string }>(({ userId }) => {
-  const user = derived(async ({ signal }) => {
-    const res = await fetch(`/api/users/${userId}`, { signal });
-    return res.json();
-  });
-
-  if (user.loading) return <p>Loading…</p>;
-  if (user.error) return <p>Error: {user.error.message}</p>;
-  return <p>{user()?.name}</p>;
-});
+const items = atom([{ n: 1 }, { n: 2 }]);
+const total = atom(() => items().reduce((sum, item) => sum + item.n, 0));
 ```
 
-Async generators stream: each yielded value feeds the envelope. Stale runs abort via the passed `signal`.
-
-### `action(fn)`
-
-Define a reusable operation with reactive execution state. Use it when you render `pending`, `data`, or `error`, or when you need unmount cancellation:
+Atoms hold data. Do not store JSX in an atom.
 
-```tsx
-const save = action(async (form: FormData, { signal }) => {
-  const response = await fetch("/save", { method: "POST", body: form, signal });
-  return response.json();
-});
-
-save(payload);
-save.pending;
-save.data;
-save.error;
-```
-
-Direct action references work as native event handlers (`onclick={save}`). Use plain functions for ordinary operations.
+---
 
-### `effect(fn)` and `effect.once(fn)`
+## Streams, when, watch, wait
 
-`effect()` runs a reactive side effect that reruns when its dependencies change, with cleanup before rerun and on unmount:
+Use a generator when you `yield*` instructions.
 
 ```tsx
-const App = ilha(() => {
-  effect(() => {
-    document.title = count();
-    return () => {
-      /* cleanup */
-    };
+import * as Stream from "effect/Stream";
+import * as Atom from "effect/unstable/reactivity/Atom";
+import { atom, when } from "ilha";
+
+const Search = function* () {
+  const q = atom("");
+  yield (
+    <input value={q} oninput={(e: Event) => q.set((e.currentTarget as HTMLInputElement).value)} />
+  );
+  yield* when(Atom.toStream(q.atom).pipe(Stream.debounce("200 millis")), function* (query) {
+    if (!query) return;
+    yield <p>{query}</p>;
   });
-  return <p>{count()}</p>;
-});
-```
-
-`effect.once()` runs once after mount for one-time setup. It receives `{ host, signal, hydrated }` and supports cleanup. `effect()` and `effect.once()` are client-only; SSR never invokes them.
-
-### `onError(fn)`
-
-Register a per-island error handler. Context: `{ error, source, host }` with sources `"effect"`, `"once"`, `"event"`, and `"action"`. Fall back to the global [`onUncaughtError()`](#onuncaughterrorfn) for app-wide sinks.
-
-## Typed props and validation
-
-Pass a [Standard Schema](https://standardschema.dev)-compatible validator as the first `ilha()` argument to validate, coerce, and default props at runtime:
-
-```tsx
-import { z } from "zod";
-
-const Greeting = ilha(z.object({ name: z.string().default("World") }), ({ name }) => (
-  <p>Hello, {name}!</p>
-));
+};
 ```
 
-Validation runs during SSR, hydration, mount, and prop updates.
+- `when(stream, body)` — render `body` for each value (SSR takes the first).
+- `watch(source, fn)` — side effect on an atom or Stream.
+- `wait(body)` — paint until `done(value)`, then continue the generator.
 
-## Composing Islands
+Map a Stream of arrays to JSX for lists (`Stream.map`, `Atom.toStream`).
 
-Nest islands as JSX components. Child islands render inline during SSR and mount independently on the client — a state change in a child does not re-render the parent:
-
-```tsx
-const Badge = ilha<{ label: string }>(({ label }) => <strong>{label}</strong>);
-
-const Page = ilha(() => <Badge label="New" />);
-```
-
-Each nested island is wrapped in a slot element (default `div`). Choose the wrapper tag with the child's `{ as }` constructor option:
-
-```tsx
-const Row = ilha(({ label }) => <li>{label}</li>, { as: "li" });
-```
+---
 
-For keyed child islands in lists, create a keyed component with `Island.key()` before rendering it so identity — state, DOM, and focus — survives reorders:
+## SSR
 
 ```tsx
-const Item = ilha<{ label: string }>(({ label }) => <li>{label}</li>);
-
-const List = ilha(() => (
-  <ul>
-    {items.map((item) => {
-      const Keyed = Item.key(item.id);
-      return <Keyed label={item.label} />;
-    })}
-  </ul>
-));
-```
-
-Keys must be unique within a parent render and cannot contain `:`.
-
-## Island Interface
-
-### `island.toString(props?)`
-
-Synchronous SSR:
-
-```ts
-Counter.toString(); // → string
-```
-
-If the island declares async `derived()` values, `toString()` renders their loading state — use `await toStringAsync()` instead (a dev warning tells you when this happens).
-
-### `await island.toStringAsync(props?)`
-
-Async SSR — awaits async derived values and pulls the first value from async-generator derived values:
-
-```ts
-const html = await Counter.toStringAsync();
-```
-
-### `island.mount(host, props?)`
-
-Mount into a DOM element. Returns an unmount function that stops listeners, effects, and other active behavior:
-
-```ts
-const unmount = Counter.mount(document.getElementById("app"));
-```
-
-### `await island.hydratable(props, options)`
-
-Emit hydration markup with serialized props and an optional state snapshot. `name` must match the client registry key:
-
-```ts
-// Server
-const html = await Counter.hydratable({}, { name: "Counter", snapshot: true });
-```
-
-```ts
-// Client
-mount({ Counter });
-```
-
-Snapshots are positional: state and derived values restore by primitive order. Malformed or incompatible snapshots are ignored safely.
+import { atom, renderToString, mount } from "ilha";
 
-### `island.key(key)`
+const Counter = () => {
+  const count = atom(0);
+  return <p>{count}</p>;
+};
 
-Create a keyed child invocation for stable slot identity in lists (see [Composing Islands](#composing-islands)).
+const html = await renderToString(Counter);
+// <div data-ilha data-ilha-state="…"><p>0</p></div>
 
-### `island.define(tagName, options?)`
-
-Register the island as a custom element, usable from plain HTML or any framework:
-
-```ts
-Counter.define("x-counter", { observe: ["start"] });
-```
-
-## Top-level Helpers
-
-### `mount(registry, options?)`
-
-Auto-discover and mount `[data-ilha="Name"]` hosts:
-
-```ts
-mount({ Counter, Badge });
+const host = document.querySelector("[data-ilha]");
+if (host) mount(host, Counter, { hydrate: true });
 ```
 
-Pass `{ root, lazy }` to scope discovery to a root element or defer mounting until hosts scroll into view.
+| Option           | Default | Meaning                        |
+| ---------------- | ------- | ------------------------------ |
+| `snapshot`       | `true`  | Embed atom values              |
+| `markers`        | `true`  | Wrap in `<div data-ilha>`      |
+| `timeout`        | none    | Serialize after this many ms   |
+| `captureActions` | `false` | Probe handlers for server RPCs |
 
-### `signal(initial)`
+In Node, `renderToString` registers happy-dom when `document` is missing.
 
-Create a free-standing signal for shared state. Same accessor shape as `state()` but lives outside any island:
-
-```ts
-const count = signal(0);
-count(); // read
-count(5); // write
-```
-
-### `computed(fn)`
-
-Create a lazy, cached, read-only value derived from signals:
-
-```ts
-const total = computed(() => price() * qty());
-```
-
-### `effect(fn)`
+---
 
-Run a standalone reactive effect outside any island; returns a stop function:
+## JSX
 
-```ts
-const stop = effect(() => {
-  document.title = `${count()} items`;
-});
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "ilha"
+  }
+}
 ```
 
-Inside an island render, `effect()` registers an island effect slot instead.
+Event props are lowercase (`onclick`, `onchange`). Use `class`, not `className`. Use `h()` when you cannot use JSX.
 
-### `context(key, initial)`
+---
 
-Get or create a keyed, app-wide shared signal:
+## Custom elements
 
 ```ts
-const theme = context("app.theme", "light");
-```
-
-### `batch(fn)` / `untrack(fn)`
+import { atom } from "ilha";
+import { define } from "ilha/define";
 
-`batch()` groups multiple writes into one propagation pass. `untrack()` reads signals without subscribing the surrounding scope:
-
-```ts
-batch(() => {
-  a(1);
-  b(2);
+define("ilha-counter", () => {
+  const count = atom(0);
+  return (
+    <button type="button" onclick={() => count.update((n: number) => n + 1)}>
+      {count}
+    </button>
+  );
 });
-
-const value = untrack(() => secret());
 ```
 
-### `persist(accessor, key)`
-
-Keep a standalone signal in sync with `localStorage`:
-
-```ts
-persist(cart, "cart");
+```html
+<ilha-counter data-ilha></ilha-counter>
 ```
 
-### `onUncaughtError(fn)`
-
-Register an app-wide error sink for islands with no local `onError()`:
-
-```ts
-const stop = onUncaughtError((error, source) => telemetry.capture(error, { source }));
-```
-
-### `html` / `raw`
-
-`html\`…\``is an XSS-safe tagged template that accepts signals, arrays, and nested templates.`raw(str)` opts into trusted markup:
-
-```ts
-import { html, raw } from "ilha";
-
-html`<p>${count()}</p>`;
-html`<button>${raw(icon)}</button>`;
-```
-
-## Bindings
-
-Use `bind:*` inside JSX or `html`` for two-way form synchronization:
-
-```tsx
-<input bind:value={name} />
-<input type="checkbox" bind:checked={done} />
-```
-
-Supported kinds: `bind:value`, `bind:checked`, `bind:group`, `bind:open`, `bind:files`, and `bind:this`. Native event props keep modifiers `:once`, `:capture`, `:passive`, and `:abortable`.
+---
 
-## Security
+## Routing and Astro
 
-JSX children and attributes are escaped by default. Use `raw()` only for trusted markup you control. `srcdoc` is always dropped, disallowed URL schemes are stripped, and unsafe inline styles are rejected.
+- [`@ilha/router`](https://github.com/ilhajs/ilha/tree/main/packages/router) — file-system SPA routes and Oxide server islands.
+- [`@ilha/astro`](https://github.com/ilhajs/ilha/tree/main/packages/astro) — Astro renderer (`renderToString` + `mount`).
 
-## TypeScript
+Docs: [ilha.build](https://ilha.build)
 
-Configure JSX with the automatic runtime:
+---
 
-```json
-{
-  "compilerOptions": {
-    "jsx": "react-jsx",
-    "jsxImportSource": "ilha"
-  }
-}
-```
+## License
 
-Build tools resolve `ilha/jsx-runtime` in production and `ilha/jsx-dev-runtime` in development.
+MIT

package/dist/define.d.ts

@@ -0,0 +1,5 @@
+import { n as Component } from "./types-DU46exHq.js";
+//#region src/define.d.ts
+declare function define(name: string, component: Component): void;
+//#endregion
+export { define };

package/dist/define.js

@@ -0,0 +1,18 @@
+import { t as mount } from "./mount-Dcy4teaf.js";
+
+//#region src/define.ts
+function define(name, component) {
+	customElements.define(name, class extends HTMLElement {
+		#unmount;
+		connectedCallback() {
+			this.#unmount = mount(this, component, { hydrate: this.hasAttribute("data-ilha") });
+		}
+		disconnectedCallback() {
+			this.#unmount?.();
+			this.#unmount = void 0;
+		}
+	});
+}
+
+//#endregion
+export { define };

package/dist/index.d.ts

@@ -1,2 +1,35 @@
-import { A as action, B as isSafeUrl, C as PersistOptions, D as SignalSetter, E as SignalAccessor, F as each, G as mount, H as isUrlAttributeName, I as effect, J as persist, K as onError, L as html, M as context, N as css, O as SignalWriter, P as derived, Q as untrack, R as ilha, S as NativeEventModifier, T as RawHtml, U as json, V as isSafeUrlAttrValue, W as morph, X as serializeStyle, Y as raw, Z as state, _ as KeyedIsland, a as EachKeyedBuilder, b as NativeEventContext, c as EffectFn, d as ErrorContext, f as ErrorSource, g as IslandComponent, h as Island, i as EachBuilder, j as batch, k as StateAccessor, l as EffectOnceContext, m as HydratableOptions, n as DerivedAccessor, o as EachResult, p as ExternalSignal, q as onUncaughtError, r as DerivedValue, s as EffectContext, t as ActionAccessor, u as EffectOnceFn, v as MountOptions, w as PersistStorage, x as NativeEventHandler, y as MountResult, z as ilhaSignal } from "./index-BETRqz-0.js";
-export { ActionAccessor, DerivedAccessor, DerivedValue, EachBuilder, EachKeyedBuilder, EachResult, EffectContext, EffectFn, EffectOnceContext, EffectOnceFn, ErrorContext, ErrorSource, ExternalSignal, HydratableOptions, Island, IslandComponent, KeyedIsland, MountOptions, MountResult, NativeEventContext, NativeEventHandler, NativeEventModifier, PersistOptions, PersistStorage, RawHtml, SignalAccessor, SignalSetter, SignalWriter, StateAccessor, action, batch, context, css, derived, each, effect, html, ilha, ilhaSignal, isSafeUrl, isSafeUrlAttrValue, isUrlAttributeName, json, morph, mount, onError, onUncaughtError, persist, raw, serializeStyle, state, untrack };
+import { a as Instruction, c as Yielded, i as Fragment, n as Component, r as Done, s as View, t as AtomHandle } from "./types-DU46exHq.js";
+import { t as h } from "./vnode-BZLcG8lC.js";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import * as Atom from "effect/unstable/reactivity/Atom";
+import "effect/Scope";
+import { AtomRegistry } from "effect/unstable/reactivity/AtomRegistry";
+//#region src/atom.d.ts
+declare function atom<A>(init: () => A): AtomHandle<A>;
+declare function atom<A>(init: A | Atom.Atom<A> | Effect.Effect<A, any, any> | Stream.Stream<A, any, any>): AtomHandle<A>;
+//#endregion
+//#region src/when.d.ts
+declare function when<A, E = never, R = never>(stream: Stream.Stream<A, E, R>, body: (value: A) => Generator<Yielded, View | void, unknown>): Instruction<void, E>;
+//#endregion
+//#region src/watch.d.ts
+declare function watch<A>(source: AtomHandle<A> | Atom.Atom<A> | Stream.Stream<A, any, any>, fn: (value: A) => void): Instruction<void>;
+//#endregion
+//#region src/wait.d.ts
+declare function wait<A>(body: (done: Done<A>) => Generator<Yielded, View | void, unknown>): Instruction<A>;
+//#endregion
+//#region src/mount.d.ts
+type RenderToStringOptions = {
+  snapshot?: boolean;
+  markers?: boolean;
+  timeout?: number;
+  captureActions?: boolean;
+};
+type MountOptions = {
+  hydrate?: boolean;
+  onError?: (error: unknown) => void;
+};
+declare function mount(el: Element, fn: Component, opts?: MountOptions): () => void;
+declare function renderToString(fn: Component, opts?: RenderToStringOptions): Promise<string>;
+//#endregion
+export { type AtomHandle, type Component, type Done, Fragment, type MountOptions, type RenderToStringOptions, type View, atom, h, mount, renderToString, wait, watch, when };