@zoijs/core 1.2.0 → 1.3.1

package/src/index.d.ts

@@ -1,164 +1,185 @@
-// Type definitions for Zoijs.
-//
-// Zoijs is authored in plain JavaScript; these declarations add editor
-// autocomplete and optional type-checking WITHOUT converting the project to
-// TypeScript. Using them is entirely opt-in — JS users are unaffected.
-
-/** A reactive value created by {@link createState}. */
-export interface State<T> {
-  /** Read the current value. Inside a binding/effect this subscribes to it. */
-  get(): T;
-  /** Write a new value. Dependents update only if the value actually changed. */
-  set(next: T): void;
-  /** Read the current value WITHOUT subscribing. */
-  peek(): T;
-}
-
-/** A lazy, cached, value-gated derived value created by {@link computed}. */
-export interface Computed<T> {
-  /** Read the current value. Recomputes only if a dependency changed. */
-  get(): T;
-  /** Read without subscribing. */
-  peek(): T;
-}
-
-declare const templateBrand: unique symbol;
-/**
- * The result of an `html` template. Pass it to {@link mount}, return it from a
- * component, or place it in another template. Treat it as opaque.
- */
-export interface TemplateResult {
-  readonly [templateBrand]: true;
-}
-
-declare const eachBrand: unique symbol;
-/** The result of {@link each}. Place it in a template's child position. */
-export interface EachResult {
-  readonly [eachBrand]: true;
-}
-
-/** A component is a function that returns an `html` template. */
-export type Component = () => TemplateResult;
-
-/**
- * A callback ref. Place it on an element as `ref=${fn}`; it receives the real DOM
- * element once the surrounding render has been inserted (deferred one microtask,
- * so `focus()` / `scrollIntoView()` / `getBoundingClientRect()` work). It may
- * return a cleanup function, which runs on unmount or list-item removal. It runs
- * once and is not reactive.
- *
- * ```ts
- * html`<input ref=${(el: HTMLInputElement) => el.focus()} />`
- * html`<div ref=${(el) => { const c = chart(el); return () => c.destroy(); }}></div>`
- * ```
- */
-export type Ref<E extends Element = Element> = (element: E) => void | (() => void);
-
-/**
- * Tagged-template function — write your markup as HTML.
- *
- * ```js
- * html`<button onclick=${() => count.set(count.get() + 1)}>${() => count.get()}</button>`
- * ```
- *
- * To reach the rendered DOM element, add a callback `ref` (see {@link Ref}):
- * `html\`<input ref=${(el) => el.focus()} />\``.
- */
-export function html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
-
-/**
- * Render a component (or a template) into a DOM element or CSS selector.
- * Returns an `unmount()` that detaches the DOM and disposes all reactivity.
- */
-export function mount(component: Component | TemplateResult, target: Element | string): () => void;
-
-/**
- * Create a reactive value.
- *
- * ```ts
- * const count = createState(0);        // State<number>
- * const name = createState<string>(""); // explicit
- * ```
- */
-export function createState<T>(initial: T, equals?: (a: T, b: T) => boolean): State<T>;
-
-/**
- * Create a lazy, cached derived value.
- *
- * ```ts
- * const fullName = computed(() => `${first.get()} ${last.get()}`); // Computed<string>
- * ```
- */
-export function computed<T>(fn: () => T, equals?: (a: T, b: T) => boolean): Computed<T>;
-
-/** A disposable handle returned by {@link effect}. */
-export interface EffectHandle {
-  /** Dispose the effect now. It also auto-disposes with its owner (component/list item). */
-  dispose(): void;
-}
-
-/**
- * Run a side effect that re-runs whenever a reactive value it reads changes.
- * Runs once immediately, then again (batched on a microtask) on any change.
- * Dependencies are tracked automatically — there is no dependency array.
- *
- * The function may return a cleanup function (same convention as a `ref`); it
- * runs **before the next run** and **on dispose**. Use the return value for
- * per-run teardown — `onCleanup` is component-scoped (fires on unmount), not
- * per-run.
- *
- * Created inside a component or list item, it auto-disposes with that scope;
- * created at module top level, it lives until you call `dispose()`.
- *
- * ```ts
- * // persist on change
- * effect(() => localStorage.setItem("theme", theme.get()));
- *
- * // per-run cleanup
- * effect(() => {
- *   const id = setInterval(() => poll(query.get()), 1000);
- *   return () => clearInterval(id);
- * });
- * ```
- *
- * For reactive *content on screen*, use a binding (`${() => …}`), not an effect.
- */
-export function effect(fn: () => void | (() => void)): EffectHandle;
-
-/**
- * Keyed list rendering. `items` may be a reactive function or a plain array;
- * `keyFn` returns a stable unique key; `renderFn` returns the template for one item.
- *
- * ```ts
- * each(() => todos.get(), (t) => t.id, (t) => html`<li>${() => t.text}</li>`)
- * ```
- */
-export function each<T>(
-  items: () => readonly T[],
-  keyFn: (item: T) => unknown,
-  renderFn: (item: T) => TemplateResult
-): EachResult;
-export function each<T>(
-  items: readonly T[],
-  keyFn: (item: T) => unknown,
-  renderFn: (item: T) => TemplateResult
-): EachResult;
-
-/** Toggle development warnings (default: `dev` is `true`). */
-export function configure(options: { dev?: boolean }): void;
-
-/**
- * Register a teardown function for the current component or list item. It runs
- * when that component is unmounted or that list item is removed. Use it for
- * timers, subscriptions, or third-party widgets created during setup.
- *
- * ```ts
- * function Clock() {
- *   const now = createState(Date.now());
- *   const id = setInterval(() => now.set(Date.now()), 1000);
- *   onCleanup(() => clearInterval(id));
- *   return html`<time>${() => now.get()}</time>`;
- * }
- * ```
- */
-export function onCleanup(fn: () => void): void;
+// Type definitions for Zoijs.
+//
+// Zoijs is authored in plain JavaScript; these declarations add editor
+// autocomplete and optional type-checking WITHOUT converting the project to
+// TypeScript. Using them is entirely opt-in — JS users are unaffected.
+
+/** A reactive value created by {@link createState}. */
+export interface State<T> {
+  /** Read the current value. Inside a binding/effect this subscribes to it. */
+  get(): T;
+  /** Write a new value. Dependents update only if the value actually changed. */
+  set(next: T): void;
+  /** Read the current value WITHOUT subscribing. */
+  peek(): T;
+}
+
+/** A lazy, cached, value-gated derived value created by {@link computed}. */
+export interface Computed<T> {
+  /** Read the current value. Recomputes only if a dependency changed. */
+  get(): T;
+  /** Read without subscribing. */
+  peek(): T;
+}
+
+declare const templateBrand: unique symbol;
+/**
+ * The result of an `html` template. Pass it to {@link mount}, return it from a
+ * component, or place it in another template. Treat it as opaque.
+ */
+export interface TemplateResult {
+  readonly [templateBrand]: true;
+}
+
+declare const eachBrand: unique symbol;
+/** The result of {@link each}. Place it in a template's child position. */
+export interface EachResult {
+  readonly [eachBrand]: true;
+}
+
+/** A component is a function that returns an `html` template. */
+export type Component = () => TemplateResult;
+
+/**
+ * A callback ref. Place it on an element as `ref=${fn}`; it receives the real DOM
+ * element once the surrounding render has been inserted (deferred one microtask,
+ * so `focus()` / `scrollIntoView()` / `getBoundingClientRect()` work). It may
+ * return a cleanup function, which runs on unmount or list-item removal. It runs
+ * once and is not reactive.
+ *
+ * ```ts
+ * html`<input ref=${(el: HTMLInputElement) => el.focus()} />`
+ * html`<div ref=${(el) => { const c = chart(el); return () => c.destroy(); }}></div>`
+ * ```
+ */
+export type Ref<E extends Element = Element> = (element: E) => void | (() => void);
+
+/**
+ * Tagged-template function — write your markup as HTML.
+ *
+ * ```js
+ * html`<button onclick=${() => count.set(count.get() + 1)}>${() => count.get()}</button>`
+ * ```
+ *
+ * To reach the rendered DOM element, add a callback `ref` (see {@link Ref}):
+ * `html\`<input ref=${(el) => el.focus()} />\``.
+ */
+export function html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
+
+/**
+ * Render a component (or a template) into a DOM element or CSS selector.
+ * Returns an `unmount()` that detaches the DOM and disposes all reactivity.
+ */
+export function mount(component: Component | TemplateResult, target: Element | string): () => void;
+
+/**
+ * Create a reactive value.
+ *
+ * ```ts
+ * const count = createState(0);        // State<number>
+ * const name = createState<string>(""); // explicit
+ * ```
+ */
+export function createState<T>(initial: T, equals?: (a: T, b: T) => boolean): State<T>;
+
+/**
+ * Create a lazy, cached derived value.
+ *
+ * ```ts
+ * const fullName = computed(() => `${first.get()} ${last.get()}`); // Computed<string>
+ * ```
+ */
+export function computed<T>(fn: () => T, equals?: (a: T, b: T) => boolean): Computed<T>;
+
+/** A disposable handle returned by {@link effect}. */
+export interface EffectHandle {
+  /** Dispose the effect now. It also auto-disposes with its owner (component/list item). */
+  dispose(): void;
+}
+
+/**
+ * Run a side effect that re-runs whenever a reactive value it reads changes.
+ * Runs once immediately, then again (batched on a microtask) on any change.
+ * Dependencies are tracked automatically — there is no dependency array.
+ *
+ * The function may return a cleanup function (same convention as a `ref`); it
+ * runs **before the next run** and **on dispose**. Use the return value for
+ * per-run teardown — `onCleanup` is component-scoped (fires on unmount), not
+ * per-run.
+ *
+ * Created inside a component or list item, it auto-disposes with that scope;
+ * created at module top level, it lives until you call `dispose()`.
+ *
+ * ```ts
+ * // persist on change
+ * effect(() => localStorage.setItem("theme", theme.get()));
+ *
+ * // per-run cleanup
+ * effect(() => {
+ *   const id = setInterval(() => poll(query.get()), 1000);
+ *   return () => clearInterval(id);
+ * });
+ * ```
+ *
+ * For reactive *content on screen*, use a binding (`${() => …}`), not an effect.
+ */
+export function effect(fn: () => void | (() => void)): EffectHandle;
+
+/**
+ * Keyed list rendering. `items` may be a reactive function or a plain array;
+ * `keyFn` returns a stable unique key; `renderFn` returns the template for one item.
+ *
+ * ```ts
+ * each(() => todos.get(), (t) => t.id, (t) => html`<li>${() => t.text}</li>`)
+ * ```
+ */
+export function each<T>(
+  items: () => readonly T[],
+  keyFn: (item: T) => unknown,
+  renderFn: (item: T) => TemplateResult
+): EachResult;
+export function each<T>(
+  items: readonly T[],
+  keyFn: (item: T) => unknown,
+  renderFn: (item: T) => TemplateResult
+): EachResult;
+
+/**
+ * Render `child`; if it **throws synchronously while building its markup** (a
+ * setup/render error that would otherwise break the whole `mount`), tear down the
+ * partial work and render `fallback` instead. Place the call in a template slot.
+ *
+ * Catches synchronous setup/render throws only. Errors in reactive *updates* are
+ * already contained per binding by the core; *async* errors belong to
+ * `@zoijs/resource` / `@zoijs/action`'s `error()` state. It renders once (no reset
+ * — re-mount the subtree to retry), logs in dev, and is silent in production.
+ *
+ * ```ts
+ * html`<section>
+ *   ${boundary(() => RiskyWidget(), (err) => html`<p>Couldn't load this.</p>`)}
+ * </section>`
+ * ```
+ */
+export function boundary<C, F>(
+  child: (() => C) | C,
+  fallback: ((error: unknown) => F) | F
+): C | F;
+
+/** Toggle development warnings (default: `dev` is `true`). */
+export function configure(options: { dev?: boolean }): void;
+
+/**
+ * Register a teardown function for the current component or list item. It runs
+ * when that component is unmounted or that list item is removed. Use it for
+ * timers, subscriptions, or third-party widgets created during setup.
+ *
+ * ```ts
+ * function Clock() {
+ *   const now = createState(Date.now());
+ *   const id = setInterval(() => now.set(Date.now()), 1000);
+ *   onCleanup(() => clearInterval(id));
+ *   return html`<time>${() => now.get()}</time>`;
+ * }
+ * ```
+ */
+export function onCleanup(fn: () => void): void;

package/src/index.js

@@ -8,6 +8,7 @@
 export { html } from "./core/html.js";
 export { mount } from "./core/mount.js";
 export { each } from "./core/each.js";
+export { boundary } from "./core/boundary.js";
 export { createState } from "./reactivity/state.js";
 export { computed } from "./reactivity/computed.js";
 export { effect } from "./reactivity/effect.js";