ilha 0.8.5 → 0.9.1

package/README.md

@@ -766,6 +766,83 @@ const styles = css`
 
 ---
 
+## JSX Runtime
+
+Prefer JSX over the `html` tag? `ilha` ships a JSX runtime (`ilha/jsx-runtime`) that produces the same XSS-safe output — JSX expressions evaluate to the same `RawHtml` values the `html` tag returns, so the two syntaxes are interchangeable and can be mixed freely.
+
+### Setup
+
+Enable the automatic JSX transform in `tsconfig.json` (works with TypeScript, Bun, Vite, esbuild, etc.):
+
+```jsonc
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "ilha",
+  },
+}
+```
+
+### Usage
+
+```tsx
+import ilha from "ilha";
+
+const Counter = ilha
+  .state("count", 0)
+  .on("button@click", ({ state }) => state.count(state.count() + 1))
+  .render(({ state }) => (
+    <div>
+      <p>Count: {state.count}</p>
+      <button>Increment</button>
+    </div>
+  ));
+```
+
+Interpolated children follow the same rules as the `html` tag — strings are escaped, signal accessors are auto-called, islands become hydration slots, arrays are flattened. Use `raw()` to opt out of escaping, and `<></>` (Fragment) to group siblings without a wrapper element.
+
+### Attributes
+
+| Feature               | Behaviour                                                                                                          |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `class` / `className` | Accepts a string, an array (`["a", cond && "b"]`), or an object (`{ active: isActive }`)                           |
+| `htmlFor`             | Alias for `for`                                                                                                    |
+| `style`               | Accepts a string or an object (`{ backgroundColor: "teal" }` → `background-color:teal`)                            |
+| Boolean attributes    | `true` renders the bare attribute, `false`/`null`/`undefined` omit it                                              |
+| `bind:*`              | Two-way bindings, same as in `html` templates — pass a signal accessor: `<input bind:value={state.name} />`        |
+| `key`                 | Keys a child island for reorder-safe rendering (same as `.key()`). Keys must be non-empty and must not contain `:` |
+
+For safety, `on*` attributes (e.g. `onclick`) and `srcdoc` are stripped — attach event listeners with `.on()` instead — and URL attributes (`href`, `src`, `action`, …) with unsafe schemes like `javascript:` are dropped.
+
+### Islands as components
+
+Islands are plain functions, so they compose as JSX components — props and keys work as you'd expect:
+
+```tsx
+const Badge = ilha
+  .input<{ label: string }>()
+  .render(({ input }) => <span class="badge">{input.label}</span>);
+
+const Card = ilha.render(() => (
+  <div class="card">
+    <Badge label="New" />
+    <p>Card content</p>
+  </div>
+));
+
+const List = ilha.render(() => (
+  <ul>
+    {items.map((item) => (
+      <li>
+        <Item key={item.id} name={item.name} />
+      </li>
+    ))}
+  </ul>
+));
+```
+
+---
+
 ## SSR + Hydration
 
 The recommended SSR + hydration pattern uses `.hydratable()` on the server and `ilha.mount()` on the client.

package/dist/{index-BUonLJXu.d.ts → index-C0SWn9oq.d.ts}

@@ -61,7 +61,7 @@ type ContextSignal<T> = {
   (): T;
   (value: T): void;
 };
-declare function ilhaContext<T>(key: string, initial: T): ContextSignal<T>;
+declare function ilhaContextFn<T>(key: string, initial: T): ContextSignal<T>;
 /**
  * Create a free-standing reactive signal that lives outside any island.
  * Useful for sharing state across islands without prop drilling, or for
@@ -74,6 +74,33 @@ declare function ilhaContext<T>(key: string, initial: T): ContextSignal<T>;
  * so when the signal changes, dependents re-run as if it were local state.
  */
 declare function ilhaSignal<T>(initial: T): SignalAccessor<T>;
+/**
+ * Create a free-standing read-only reactive value derived from other signals.
+ * The computation is lazy and cached: `fn` re-runs only when a signal it read
+ * changed and the computed is read again. Reading it inside a `.derived()`,
+ * `.effect()`, `.render()`, or top-level `effect()` subscribes that scope —
+ * dependents re-run when the computed's value changes.
+ *
+ * ```ts
+ * const items = ilha.signal([1, 2, 3]);
+ * const total = ilha.computed(() => items().reduce((a, b) => a + b, 0));
+ * ```
+ */
+declare function ilhaComputed<T>(fn: () => T): SignalAccessor<T>;
+/**
+ * Run a free-standing reactive effect outside any island. `fn` runs once
+ * immediately and again whenever a signal it read changes. It may return a
+ * cleanup function, invoked before each re-run and on stop. Signal writes
+ * inside the effect are batched. Returns a stop function that disposes the
+ * effect and runs the final cleanup.
+ *
+ * ```ts
+ * const stop = effect(() => {
+ *   document.title = `${cart.count()} items`;
+ * });
+ * ```
+ */
+declare function ilhaEffect(fn: () => void | (() => void)): () => void;
 /**
  * Run `fn` with reactive tracking suspended. Reading signals inside `fn`
  * returns their current value without subscribing the surrounding scope.
@@ -134,6 +161,17 @@ interface Island<TInput = Record<string, unknown>, _TStateMap extends Record<str
   mount(host: Element, props?: Partial<TInput>): () => void;
   hydratable(props: Partial<TInput>, options: HydratableOptions): Promise<string>;
   key(key: string): KeyedIsland<TInput>;
+  /**
+   * Register this island as a custom element, usable from plain HTML or any
+   * framework: `Counter.define("x-counter", { observe: ["label"] })` then
+   * `<x-counter label="hi"></x-counter>`. Observed attributes become string
+   * input props and re-resolve input on change; richer props can be assigned
+   * via the element's `props` property. Mounts on connect, unmounts on
+   * disconnect. No-op (with a dev warning) where customElements is missing.
+   */
+  define(tagName: string, options?: {
+    observe?: string[];
+  }): void;
   [ISLAND]: true;
 }
 interface KeyedIsland<TInput> {
@@ -290,8 +328,12 @@ declare const ilha: IlhaBuilder<Record<string, unknown>, Record<never, never>, R
   raw: typeof ilhaRaw;
   mount: typeof mountAll;
   from: typeof ilhaFrom;
-  context: typeof ilhaContext;
+  context: typeof ilhaContextFn & {
+    /** Remove a context signal from the registry. Returns true if it existed. */delete(key: string): boolean; /** Remove all context signals from the registry (e.g. between tests). */
+    clear(): void;
+  };
   signal: typeof ilhaSignal;
+  computed: typeof ilhaComputed;
   batch: typeof batch;
   untrack: typeof untrack;
   onUncaughtError: typeof onUncaughtError;
@@ -303,6 +345,9 @@ declare const raw: typeof ilhaRaw;
 declare const css: typeof ilhaCss;
 declare const mount: typeof mountAll;
 declare const from: typeof ilhaFrom;
-declare const context: typeof ilhaContext;
+declare const context: typeof ilhaContextFn & {
+  /** Remove a context signal from the registry. Returns true if it existed. */delete(key: string): boolean; /** Remove all context signals from the registry (e.g. between tests). */
+  clear(): void;
+};
 //#endregion
-export { raw as A, css as C, ilhaSignal as D, ilha as E, mount as O, context as S, html as T, OnMountContext as _, ErrorSource as a, __ilhaJsxSlot as b, HandlerContextFor as c, Island as d, IslandDerived as f, MountResult as g, MountOptions as h, ErrorContext as i, untrack as j, onUncaughtError as k, HydratableOptions as l, KeyedIsland as m, DerivedValue as n, ExternalSignal as o, IslandState as p, EffectContext as r, HandlerContext as s, DerivedAccessor as t, ISLAND_MOUNT_INTERNAL as u, RawHtml as v, from as w, batch as x, SignalAccessor as y };
+export { mount as A, css as C, ilhaComputed as D, ilha as E, raw as M, untrack as N, ilhaEffect as O, context as S, html as T, OnMountContext as _, ErrorSource as a, __ilhaJsxSlot as b, HandlerContextFor as c, Island as d, IslandDerived as f, MountResult as g, MountOptions as h, ErrorContext as i, onUncaughtError as j, ilhaSignal as k, HydratableOptions as l, KeyedIsland as m, DerivedValue as n, ExternalSignal as o, IslandState as p, EffectContext as r, HandlerContext as s, DerivedAccessor as t, ISLAND_MOUNT_INTERNAL as u, RawHtml as v, from as w, batch as x, SignalAccessor as y };

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { A as raw, C as css, D as ilhaSignal, E as ilha, O as mount, S as context, T as html, _ as OnMountContext, a as ErrorSource, b as __ilhaJsxSlot, c as HandlerContextFor, d as Island, f as IslandDerived, g as MountResult, h as MountOptions, i as ErrorContext, j as untrack, k as onUncaughtError, l as HydratableOptions, m as KeyedIsland, n as DerivedValue, o as ExternalSignal, p as IslandState, r as EffectContext, s as HandlerContext, t as DerivedAccessor, u as ISLAND_MOUNT_INTERNAL, v as RawHtml, w as from, x as batch, y as SignalAccessor } from "./index-BUonLJXu.js";
-export { DerivedAccessor, DerivedValue, EffectContext, ErrorContext, ErrorSource, ExternalSignal, HandlerContext, HandlerContextFor, HydratableOptions, ISLAND_MOUNT_INTERNAL, Island, IslandDerived, IslandState, KeyedIsland, MountOptions, MountResult, OnMountContext, RawHtml, SignalAccessor, __ilhaJsxSlot, batch, context, css, ilha as default, from, html, ilhaSignal, ilhaSignal as signal, mount, onUncaughtError, raw, untrack };
+import { A as mount, C as css, D as ilhaComputed, E as ilha, M as raw, N as untrack, O as ilhaEffect, S as context, T as html, _ as OnMountContext, a as ErrorSource, b as __ilhaJsxSlot, c as HandlerContextFor, d as Island, f as IslandDerived, g as MountResult, h as MountOptions, i as ErrorContext, j as onUncaughtError, k as ilhaSignal, l as HydratableOptions, m as KeyedIsland, n as DerivedValue, o as ExternalSignal, p as IslandState, r as EffectContext, s as HandlerContext, t as DerivedAccessor, u as ISLAND_MOUNT_INTERNAL, v as RawHtml, w as from, x as batch, y as SignalAccessor } from "./index-C0SWn9oq.js";
+export { DerivedAccessor, DerivedValue, EffectContext, ErrorContext, ErrorSource, ExternalSignal, HandlerContext, HandlerContextFor, HydratableOptions, ISLAND_MOUNT_INTERNAL, Island, IslandDerived, IslandState, KeyedIsland, MountOptions, MountResult, OnMountContext, RawHtml, SignalAccessor, __ilhaJsxSlot, batch, ilhaComputed as computed, context, css, ilha as default, ilhaEffect as effect, from, html, ilhaSignal, ilhaSignal as signal, mount, onUncaughtError, raw, untrack };