ilha 0.15.1 → 0.16.0

package/dist/test.d.ts

@@ -0,0 +1,66 @@
+import { a as Component } from "./types-NhEiBvwy.js";
+import { t as SnapshotValue } from "./snapshot-BDC74QwI.js";
+import { IlhaInspectNode } from "./debug.js";
+import { t as RenderToStringOptions } from "./mount-3Ggg67T0.js";
+//#region src/test.d.ts
+export interface RenderOptions {
+  /** Render on the server first and inject the HTML into the container. Default `false`. */
+  ssr?: boolean;
+  /**
+   * Hydrate the container instead of mounting fresh. Default: the value of
+   * `ssr`. With `hydrate: true` alone, the container must already hold
+   * server markup.
+   */
+  hydrate?: boolean;
+  /** Mount into this element. Default: a new `<div>` appended to `document.body`. */
+  container?: Element;
+  /** Called for a failing root component and for uncaught nested failures. */
+  onError?: (error: Error) => void;
+}
+export interface AtomEntry {
+  /** Name of the component that owns the atom. */
+  component: string;
+  /** Slot index, in registration order. */
+  index: number;
+  value: SnapshotValue | string;
+}
+export interface TestUi {
+  /** Errors reported through `onError` so far. */
+  readonly errors: readonly Error[];
+  /** Resolves when the mount has no pending work left. Never uses timers. */
+  settled: () => Promise<void>;
+  click: (selector: string) => Promise<void>;
+  /** Set `value` on the element, then fire a bubbling `input` event. */
+  input: (selector: string, value: string) => Promise<void>;
+  /** Set `value` (or `checked` for a boolean), then fire a bubbling `change` event. */
+  change: (selector: string, value: string | boolean) => Promise<void>;
+  /** Fire a bubbling, cancelable `submit` event. */
+  submit: (selector: string) => Promise<void>;
+  /** Dispatch any event on the first element that matches `selector`. */
+  dispatch: (selector: string, event: Event) => Promise<void>;
+  /** The container's `innerHTML`. */
+  html: () => string;
+  /** The container's `textContent`. */
+  text: () => string;
+  query: <E extends Element = Element>(selector: string) => E | null;
+  queryAll: <E extends Element = Element>(selector: string) => E[];
+  /** Live component tree from `ilha/debug`. */
+  tree: () => IlhaInspectNode[];
+  /** Every atom in the tree, in render order. */
+  atoms: () => AtomEntry[];
+  /** Stop the mount and remove a container the harness created. */
+  unmount: () => void;
+}
+/**
+ * Render `fn` to HTML without a DOM. Same output as `renderToString`, kept
+ * here so tests import both helpers from `ilha/test`.
+ */
+export declare const renderHtml: (fn: Component, opts?: RenderToStringOptions) => Promise<string>;
+/**
+ * Mount `fn` into a DOM container and return a handle that drives it.
+ * Needs a DOM global (happy-dom). With `ssr`, the server render is async:
+ * `await ui.settled()` before reading `html()`.
+ */
+export declare const render: (fn: Component, opts?: RenderOptions) => TestUi;
+//#endregion
+export type { IlhaInspectNode };

package/dist/test.js

@@ -0,0 +1,179 @@
+import { f as toError, l as isString } from "./shared-vpgYXytd.js";
+import { n as mountWithRuntime, r as renderToString } from "./mount-BwuJsiDH.js";
+import { inspect } from "./debug.js";
+
+//#region src/test.ts
+const MICROTASK_TURNS = 4;
+const SNIPPET_LENGTH = 400;
+const requireDocument = () => {
+	if (!("document" in globalThis)) throw new Error("ilha/test needs a DOM. Preload happy-dom (bunfig.toml: [test] preload = ['./happydom.ts'] with GlobalRegistrator.register()), or use renderHtml() for DOM-free assertions.");
+};
+const turn = async (left = MICROTASK_TURNS) => {
+	await Promise.resolve();
+	if (left > 1) await turn(left - 1);
+};
+const snippet = (html) => html.length > SNIPPET_LENGTH ? `${html.slice(0, SNIPPET_LENGTH)}…` : html;
+/** Write `value` (or `checked`) onto a form control; false when it has no such field. */
+const assign = (el, value) => {
+	if (isString(value)) {
+		if (!("value" in el)) return false;
+		el.value = value;
+		return true;
+	}
+	if (!("checked" in el)) return false;
+	el.checked = value;
+	return true;
+};
+const flatten = (nodes) => nodes.flatMap((node) => [...node.atoms.map(({ index, value }) => ({
+	component: node.component,
+	index,
+	value
+})), ...flatten(node.children)]);
+/**
+* Render `fn` to HTML without a DOM. Same output as `renderToString`, kept
+* here so tests import both helpers from `ilha/test`.
+*/
+const renderHtml = (fn, opts) => renderToString(fn, opts);
+/**
+* Mount `fn` into a DOM container and return a handle that drives it.
+* Needs a DOM global (happy-dom). With `ssr`, the server render is async:
+* `await ui.settled()` before reading `html()`.
+*/
+const render = (fn, opts = {}) => {
+	requireDocument();
+	const ssr = opts.ssr === true;
+	const hydrate = opts.hydrate ?? ssr;
+	const ownsContainer = opts.container === void 0;
+	const container = opts.container ?? document.createElement("div");
+	if (ownsContainer) document.body.append(container);
+	const errors = [];
+	let pending = 0;
+	let closed = false;
+	let started = false;
+	let failure;
+	let stop;
+	let host = container;
+	let waiters = [];
+	const wake = () => {
+		const woken = waiters;
+		waiters = [];
+		for (const resolve of woken) resolve();
+	};
+	const track = (runtime) => {
+		const { begin, end } = runtime;
+		runtime.begin = () => {
+			pending += 1;
+			begin();
+		};
+		runtime.end = () => {
+			pending -= 1;
+			end();
+			if (pending === 0) wake();
+		};
+	};
+	const boot = async () => {
+		try {
+			if (ssr) container.innerHTML = await renderToString(fn);
+			if (hydrate || !ssr) {
+				host = (hydrate ? container.querySelector("[data-ilha]") : null) ?? container;
+				stop = mountWithRuntime(host, fn, {
+					hydrate,
+					onError: (error) => {
+						errors.push(error);
+						opts.onError?.(error);
+					}
+				}, track);
+			}
+		} catch (error) {
+			failure = toError(error);
+		}
+		started = true;
+	};
+	const ready = boot();
+	const ensureStarted = () => {
+		if (failure) throw failure;
+		if (!started) throw new Error("ilha/test: the server render is still running. `await ui.settled()` before reading the DOM.");
+	};
+	const nextIdle = () => {
+		const { promise, resolve } = Promise.withResolvers();
+		waiters.push(() => resolve(null));
+		return promise;
+	};
+	const quiesce = async () => {
+		await turn();
+		if (pending === 0 || closed) return;
+		await nextIdle();
+		await quiesce();
+	};
+	const settled = async () => {
+		await ready;
+		ensureStarted();
+		await quiesce();
+	};
+	const requireElement = (selector) => {
+		const el = container.querySelector(selector);
+		if (!el) throw new Error(`ilha/test: no element matches "${selector}". Current HTML: ${snippet(container.innerHTML)}`);
+		return el;
+	};
+	const dispatch = async (selector, event) => {
+		await settled();
+		requireElement(selector).dispatchEvent(event);
+		await settled();
+	};
+	const setField = async (selector, type, value) => {
+		await settled();
+		const el = requireElement(selector);
+		if (!assign(el, value)) throw new Error(`ilha/test: "${selector}" is not a form control that takes ${isString(value) ? "a value" : "checked"}.`);
+		el.dispatchEvent(new Event(type, { bubbles: true }));
+		await settled();
+	};
+	const inspectRoot = () => {
+		ensureStarted();
+		return inspect(host);
+	};
+	return {
+		atoms: () => flatten(inspectRoot()),
+		change: (selector, value) => setField(selector, "change", value),
+		click: (selector) => dispatch(selector, new MouseEvent("click", {
+			bubbles: true,
+			cancelable: true
+		})),
+		dispatch,
+		get errors() {
+			return errors;
+		},
+		html: () => {
+			ensureStarted();
+			return container.innerHTML;
+		},
+		input: (selector, value) => setField(selector, "input", value),
+		query: (selector) => {
+			ensureStarted();
+			return container.querySelector(selector);
+		},
+		queryAll: (selector) => {
+			ensureStarted();
+			return [...container.querySelectorAll(selector)];
+		},
+		settled,
+		submit: (selector) => dispatch(selector, new Event("submit", {
+			bubbles: true,
+			cancelable: true
+		})),
+		text: () => {
+			ensureStarted();
+			return container.textContent ?? "";
+		},
+		tree: inspectRoot,
+		unmount: () => {
+			if (closed) return;
+			closed = true;
+			stop?.();
+			if (ownsContainer) container.remove();
+			wake();
+		}
+	};
+};
+
+//#endregion
+export { render, renderHtml };

package/dist/{types-DsdtZMhG.d.ts → types-NhEiBvwy.d.ts}

@@ -1,23 +1,19 @@
-import { Effect, Stream } from "effect";
 import { AtomRegistry } from "effect/reactivity/AtomRegistry";
 import { Closeable } from "effect/Scope";
+import { Effect, Stream } from "effect";
 import { Atom } from "effect/reactivity";
 //#region src/types.d.ts
 type JsonText = string | number | bigint | boolean | null | undefined;
 /** Runtime prop bag values painted onto elements / passed to components. */
 type PropValue = JsonText | PropBag | StyleObject | EventHandler | AtomHandle<JsonText> | readonly PropValue[];
 type StyleObject = Readonly<Record<string, string | number | null | undefined>>;
-type EventHandler = (event: Event) => void;
+/** Event and ref callbacks. `never` accepts handlers typed for a specific event. */
+type EventHandler = (event: never) => void;
 /** Indexed bag — interface so PropValue can recurse without a circular type alias. */
 interface PropBag {
   readonly [key: string]: PropValue | undefined;
 }
-type ActionArg = JsonText | PropBag | readonly ActionArg[];
-interface SsrAction {
-  readonly k: string;
-  readonly a: readonly ActionArg[];
-}
-type View = VNode | UnsafeHtml | JsonText | AtomHandle<unknown> | Stream.Stream<View, unknown, unknown> | GeneratorFn | Component | View[] | Iterable<View>;
+type View = VNode | UnsafeHtml | JsonText | AtomView | Stream.Stream<View, unknown, unknown> | GeneratorFn | Component | View[] | Iterable<View>;
 declare const Fragment: unique symbol;
 type Fragment = typeof Fragment;
 type ComponentFn = (props: PropBag) => View | Promise<View | undefined> | undefined;
@@ -45,14 +41,13 @@ type Component = (() => View | undefined | Promise<View | undefined>) | Generato
 interface IlhaRuntime {
   readonly registry: AtomRegistry;
   readonly scope: Closeable;
+  /** Run an effect synchronously with the mount's `AtomRegistry` provided. */
+  readonly fork: <A, E>(effect: Effect.Effect<A, E, AtomRegistry>) => A;
   readonly ssr: boolean;
   readonly ssrValues: unknown[];
-  ssrActions: Record<string, SsrAction>;
-  ssrEventI: number;
-  ssrCapture: boolean;
   hydrateValues?: unknown[];
   hydrateI: number;
-  nextHole: () => number;
+  holeSeq: number;
   begin: () => void;
   end: () => void;
   later: (fn: () => void) => void;
@@ -64,6 +59,11 @@ interface IlhaRuntime {
    */
   onError?: (error: Error) => void;
 }
+/** Any atom handle as a view: the painter subscribes to `atom`, whatever it holds. */
+interface AtomView {
+  readonly $$atom: 1;
+  readonly atom: Atom.Atom<unknown>;
+}
 interface AtomHandle<A> {
   readonly $$atom: 1;
   readonly atom: Atom.Atom<A>;
@@ -76,6 +76,19 @@ type AtomEquality<A> = "structural" | ((prev: A, next: A) => boolean);
 interface AtomOptions<A = unknown> {
   /** Skip subscriber notify when `equals(prev, next)` holds. Plain values only. */
   readonly equals?: AtomEquality<A>;
+  /**
+   * Set `false` to keep a plain-value slot out of the SSR snapshot. The slot
+   * starts from its initial value on hydration. Default `true`.
+   */
+  readonly snapshot?: boolean;
+}
+/** Options for `atom.lazy()`. */
+interface AtomLazyOptions {
+  /**
+   * Set `false` to keep the slot out of the SSR snapshot, for timers,
+   * observers, and other mutable refs. Default `true`.
+   */
+  readonly snapshot?: boolean;
 }
 /** Optional disposer returned from `watch.once`. */
 type WatchOnceCleanup = () => void;
@@ -89,39 +102,19 @@ interface WatchContext {
   onCleanup: (fn: () => void) => void;
 }
 type WatchCallback<A> = (value: A, ctx: WatchContext) => WatchOnceCleanup | undefined | Promise<WatchOnceCleanup | undefined>;
-/** Options for `resource()`. */
-interface ResourceOptions {
-  /** Serve cached data while revalidating in the background. Default `true`. */
-  readonly staleWhileRevalidate?: boolean;
-}
-/** Async fetch scoped to a resource key. Receives an abort signal. */
-type ResourceFetcher<T> = (key: string, ctx: {
-  signal: AbortSignal;
-}) => Promise<T>;
-/** Handles returned by `resource()`. */
-interface Resource<T> {
-  readonly data: AtomHandle<T | undefined>;
-  readonly error: AtomHandle<unknown>;
-  readonly loading: AtomHandle<boolean>;
-  refetch: () => Promise<T | undefined>;
-}
-/** Connection state of a `fromEventSource` feed. */
-type EventSourceStatus = "connecting" | "open" | "retrying" | "closed";
-/** Options for `fromEventSource()`. */
-interface EventSourceOptions<T = string> {
-  /** Named event to listen for. Default: the `message` event. */
-  readonly event?: string;
-  /** Decode (and validate) `data` into `T`. Throwing skips the message. */
-  readonly schema?: (data: string) => T;
-  /** Base backoff between reconnects. Default `1000`. Capped at 30s. */
-  readonly retryBaseMs?: number;
-}
-/** Live server-sent-events feed. */
-interface EventSourceFeed<T = string> {
-  /** Paint with `yield Stream.map(feed.stream, ...)`; watch `latest` instead in sync components. */
-  readonly stream: Stream.Stream<T, never, never>;
-  readonly status: AtomHandle<EventSourceStatus>;
-  readonly latest: AtomHandle<T | undefined>;
+interface MountOptions {
+  hydrate?: boolean;
+  /**
+   * Called with a failing root component, and with a nested component no
+   * `ErrorBoundary` caught, before the error view paints.
+   */
+  onError?: (error: Error) => void;
+  /**
+   * Called each time the mount has no pending work left: after the first
+   * paint and again after every rerender, async component, and watcher
+   * settles. Use it to learn when the DOM reflects an atom update.
+   */
+  onIdle?: () => void;
 }
 //#endregion
-export { WatchOnceCleanup as C, WatchContext as S, ResourceOptions as _, ComponentFn as a, View as b, EventSourceStatus as c, Instruction as d, JsxComponent as f, ResourceFetcher as g, Resource as h, Component as i, Fragment as l, PropValue as m, AtomHandle as n, EventSourceFeed as o, PropBag as p, AtomOptions as r, EventSourceOptions as s, AtomEquality as t, IlhaRuntime as u, UnsafeHtml as v, Yielded as w, WatchCallback as x, VNode as y };
+export { View as _, Component as a, WatchOnceCleanup as b, IlhaRuntime as c, JsxComponent as d, MountOptions as f, VNode as g, UnsafeHtml as h, AtomOptions as i, Instruction as l, PropValue as m, AtomHandle as n, ComponentFn as o, PropBag as p, AtomLazyOptions as r, Fragment as s, AtomEquality as t, JsonText as u, WatchCallback as v, Yielded as x, WatchContext as y };

package/dist/vnode-DJ25Jn3D.js

@@ -0,0 +1,22 @@
+import { a as hasBrand } from "./shared-vpgYXytd.js";
+
+//#region src/types.ts
+const Fragment = Symbol("ilha.Fragment");
+
+//#endregion
+//#region src/vnode.ts
+const createVNode = (type, props, ...rest) => {
+	const { key, children, ...own } = props ?? {};
+	return {
+		$$ilha: 1,
+		children: (children === void 0 ? rest : [children, ...rest]).flat(Number.POSITIVE_INFINITY),
+		key,
+		props: own,
+		type
+	};
+};
+const h = createVNode;
+const isVNode = (x) => hasBrand(x, "$$ilha");
+
+//#endregion
+export { isVNode as n, Fragment as r, h as t };

package/dist/{vnode-CpSQZnLM.d.ts → vnode-DskooLPD.d.ts}

@@ -1,4 +1,4 @@
-import { a as ComponentFn, b as View, f as JsxComponent, l as Fragment, n as AtomHandle, p as PropBag, y as VNode } from "./types-DsdtZMhG.js";
+import { _ as View, d as JsxComponent, g as VNode, n as AtomHandle, o as ComponentFn, p as PropBag, s as Fragment } from "./types-NhEiBvwy.js";
 //#region src/jsx-types.d.ts
 declare namespace JSX {
   export type Element = View;
@@ -592,6 +592,14 @@ declare namespace JSX {
 }
 //#endregion
 //#region src/vnode.d.ts
-declare const h: (type: string | Fragment | ComponentFn | JsxComponent, props: PropBag | null | undefined, ...rest: View[]) => VNode;
+/**
+ * Build a vnode. A component with typed props gets its props checked against
+ * that type; elements and untyped components take a plain prop bag.
+ */
+interface HFn {
+  <P>(type: (props: P) => ReturnType<JsxComponent>, props: P | null | undefined, ...rest: View[]): VNode;
+  (type: string | Fragment | ComponentFn | JsxComponent, props: PropBag | null | undefined, ...rest: View[]): VNode;
+}
+declare const h: HFn;
 //#endregion
 export { JSX as n, h as t };

package/llms.txt

@@ -0,0 +1,37 @@
+# ilha
+
+> Tiny, isomorphic islands UI library on Effect 4. Function components, order-based `atom()` slots, JSX, SSR via `renderToString`, hydration via `mount(host, C, { hydrate: true })`. Version 0.16.0.
+
+Start with the canonical-usage table: exactly one API per task, plus a never-do list.
+
+## Docs
+
+- [Choose an API](https://ilha.build/guide/getting-started/choose-an-api): task to API table and never-do list
+- [Core concepts](https://ilha.build/guide/getting-started/core-concepts): components, atoms, mount, renderToString
+- [Full docs for LLMs](https://ilha.build/llms-full.txt): every page as one Markdown file
+- [Reference](https://ilha.build/reference/ilha): API reference for ilha
+
+## Diagnostics
+
+- [Error codes](https://ilha.build/errors): ILHA001..ILHA007: cause and fix for each IlhaError
+
+## Tooling
+
+- [Testing](https://ilha.build/guide/recipes/testing): ilha/test render harness
+- [Devtools](https://ilha.build/guide/devtools): ilha/debug inspect() and @ilha/devtools
+- [Oxlint plugin](https://ilha.build/guide/recipes/oxlint): ilha/oxlint rules
+
+## Recipes
+
+- [Data fetching](https://ilha.build/guide/recipes/data-fetching): Effect Cache + atom(Effect)
+- [Server-sent events](https://ilha.build/guide/recipes/server-sent-events): Stream.callback + retry
+- [Custom elements](https://ilha.build/guide/recipes/custom-elements): wrap a component as a custom element
+
+## Optional
+
+- [Migrations](https://github.com/ilhajs/ilha/blob/main/packages/ilha/MIGRATIONS.md): removed or changed APIs with replacements
+
+## Package files
+
+- AGENTS.md: agent guide shipped in the npm tarball (public API from source JSDoc)
+- MIGRATIONS.md, MIGRATIONS.json: removed or changed APIs with replacements