@moku-labs/web 1.15.1 → 1.16.0

package/dist/{render-DLZEOe4M.cjs → render-KdufA3_b.cjs}

@@ -28,5 +28,28 @@ function renderVNode(vnode, region) {
 	region.replaceChildren();
 	(0, preact.render)(vnode, region);
 }
+/**
+* Commit a component's VNode into its host as a DIFF — the in-interaction render
+* path. Unlike {@link renderVNode} (which RESETS the region: unmount → clear → mount,
+* correct for a navigation swap of static SSR markup), this is a plain Preact
+* `render(vnode, host)` that diffs against Preact's retained vdom, preserving focus,
+* scroll, and uncontrolled input state across re-renders triggered by `ctx.set`.
+*
+* Reached ONLY through the lazy `await import("./render")` gate (the component render
+* scheduler in `components.ts`), so an app whose islands never return a VNode never
+* pulls Preact's `render` into its main bundle.
+*
+* @param vnode - The VNode produced by a component's `render(state, ctx)`.
+* @param host - The island's host element to render into.
+* @example
+* ```ts
+* const { commitVNode } = await import("./render");
+* commitVNode(h(BoardView, { snapshot }), host);
+* ```
+*/
+function commitVNode(vnode, host) {
+	(0, preact.render)(vnode, host);
+}
 //#endregion
+exports.commitVNode = commitVNode;
 exports.renderVNode = renderVNode;

package/dist/{render-BNe0s7fr.mjs → render-UO4nimWr.mjs}

@@ -28,5 +28,27 @@ function renderVNode(vnode, region) {
 	region.replaceChildren();
 	render(vnode, region);
 }
+/**
+* Commit a component's VNode into its host as a DIFF — the in-interaction render
+* path. Unlike {@link renderVNode} (which RESETS the region: unmount → clear → mount,
+* correct for a navigation swap of static SSR markup), this is a plain Preact
+* `render(vnode, host)` that diffs against Preact's retained vdom, preserving focus,
+* scroll, and uncontrolled input state across re-renders triggered by `ctx.set`.
+*
+* Reached ONLY through the lazy `await import("./render")` gate (the component render
+* scheduler in `components.ts`), so an app whose islands never return a VNode never
+* pulls Preact's `render` into its main bundle.
+*
+* @param vnode - The VNode produced by a component's `render(state, ctx)`.
+* @param host - The island's host element to render into.
+* @example
+* ```ts
+* const { commitVNode } = await import("./render");
+* commitVNode(h(BoardView, { snapshot }), host);
+* ```
+*/
+function commitVNode(vnode, host) {
+	render(vnode, host);
+}
 //#endregion
-export { renderVNode };
+export { commitVNode, renderVNode };

package/dist/testing.d.mts

@@ -0,0 +1,383 @@
+//#region src/plugins/spa/types.d.ts
+/**
+ * What a component's `render` may return:
+ * - a Preact `VNode` — committed into the host through the lazy Preact gate (`commitVNode`);
+ * - a `Node` — replaces the host's children;
+ * - a `string` — set as the host's `innerHTML`;
+ * - `void`/`undefined` — the render mutated the DOM itself (DOM-only islands → no Preact loaded).
+ */
+type RenderResult = import("preact").VNode | Node | string | void;
+/**
+ * Factory that builds a component's typed per-instance state (mirrors a plugin's
+ * `createState`). Called ONCE at mount; the returned object is stored on the
+ * {@link ComponentInstance} and exposed read-only as `ctx.state`.
+ *
+ * @param ctx - The component context for this instance (state is not yet set).
+ * @returns The initial per-instance state.
+ * @example
+ * state: (ctx): BoardState => ({ boardId: ctx.params.id ?? "", cards: [] })
+ */
+type ComponentStateFactory<S extends object> = (ctx: ComponentContext<S>) => S;
+/**
+ * Pure render of `(state, ctx)` → {@link RenderResult}. Called after mount-state-init
+ * and again (microtask-batched) after every `ctx.set`. Must be free of side effects
+ * beyond producing its result.
+ *
+ * @param state - The current per-instance state (read-only).
+ * @param ctx - The component context for this instance.
+ * @returns The render result to commit into the host.
+ * @example
+ * render: (state) => h(BoardView, { snapshot: state.snapshot })
+ */
+type ComponentRender<S extends object> = (state: Readonly<S>, ctx: ComponentContext<S>) => RenderResult;
+/**
+ * A delegated DOM event handler. `target` is the element matched by the key's selector
+ * (already resolved via `closest` — no `instanceof`/`closest` ceremony in the body).
+ *
+ * Typed `void` for ergonomics (the void-return rule accepts async handlers returning
+ * `Promise<void>` too); the kernel ignores any returned value.
+ *
+ * @param ctx - The component context (carries the live per-instance `state`).
+ * @param event - The raw DOM event.
+ * @param target - The element matched by the selector (the host when no selector).
+ * @returns void (a returned promise is ignored by the kernel).
+ * @example
+ * (ctx, event, button) => { event.preventDefault(); ctx.set({ open: true }); }
+ */
+type ComponentEventHandler<S extends object> = (ctx: ComponentContext<S>, event: Event, target: Element) => void;
+/**
+ * Declarative delegated event map. Each key is `"<type> <selector>"` (the selector is
+ * optional → a host-level listener). ONE real listener per event TYPE is attached to
+ * the host; dispatch walks `event.target.closest(selector)` within the host. All
+ * listeners are auto-removed on destroy.
+ *
+ * @example
+ * events: {
+ *   "click [data-action='delete']": (ctx, _e, btn) => ctx.set(removeCard(ctx.state, btn)),
+ *   "submit [data-add]": (ctx, e) => { e.preventDefault(); add(ctx); }
+ * }
+ */
+type ComponentEvents<S extends object> = Record<string, ComponentEventHandler<S>>;
+/**
+ * Context handed to every component lifecycle hook, render, and event handler — the
+ * bound element + page data, plus the matched route's `params`/`meta`/`locale` and a
+ * link builder, so an island can read its route context (e.g. a `card` route's
+ * `ctx.meta.focus` + `ctx.params.id`) directly, without the page bridging it through
+ * `data-*` attributes.
+ *
+ * Generic over the per-instance state `S` (default `undefined` so every existing
+ * hooks-only island still type-checks). The additive members (`state`/`set`/`flush`/
+ * `cleanup`/`component`) are ALWAYS-PRESENT functions — never optional keys — so they
+ * never trip `exactOptionalPropertyTypes`.
+ */
+interface ComponentContext<S = undefined> {
+  /** The element the component instance is bound to. */
+  el: Element;
+  /** Page data extracted from the `script#__DATA__` payload. */
+  data: PageData;
+  /** Resolved path params of the route matched for the current URL (empty if unmatched). */
+  readonly params: Record<string, string | undefined>;
+  /** The matched route's `.meta()` bag (empty if unmatched). */
+  readonly meta: Record<string, unknown>;
+  /** Active locale for the current route (empty string if unknown). */
+  readonly locale: string;
+  /** Build a link to a named route by pattern substitution (same output as `app.router.toUrl`). */
+  readonly url: (name: string, params?: Record<string, string>) => string;
+  /** The live per-instance state (the object returned by `spec.state`). `undefined` for legacy hooks-only islands. */
+  readonly state: S;
+  /**
+   * Merge a patch into the per-instance state, then schedule ONE batched render.
+   * Accepts a partial object or an updater `(prev) => partial`. A no-op for legacy
+   * islands with no `state`/`render`.
+   *
+   * @param patch - A partial state object, or an updater returning one.
+   * @returns void
+   * @example
+   * ctx.set({ open: true });
+   * ctx.set(prev => ({ count: prev.count + 1 }));
+   */
+  set(patch: Partial<S> | ((prev: Readonly<S>) => Partial<S>)): void;
+  /**
+   * Force a synchronous render now (drains any pending scheduled render). Rarely
+   * needed in app code — `ctx.set` already schedules one; mainly a test seam.
+   *
+   * @returns void
+   * @example
+   * ctx.flush();
+   */
+  flush(): void;
+  /**
+   * Register a disposer run on `onDestroy` (subscriptions, timers, manual/global
+   * listeners the declarative `events` map cannot cover). Disposers run LIFO.
+   *
+   * @param dispose - The teardown function.
+   * @returns void
+   * @example
+   * ctx.cleanup(onPatch(p => applyPatch(ctx, p)));
+   */
+  cleanup(dispose: () => void): void;
+  /**
+   * Resolve another island's registered `api` by name. Returns `undefined` when no
+   * provider is registered (optional-dependency semantics, mirroring `ctx.has`).
+   *
+   * @param name - The provider island's component name.
+   * @returns The provider's api, or `undefined`.
+   * @example
+   * ctx.component<LightboxApi>("lightbox")?.open(slides, index);
+   */
+  component<T = unknown>(name: string): T | undefined;
+}
+/** Lifecycle hooks a component may implement. Generic over the per-instance state `S`. */
+interface ComponentHooks<S = undefined> {
+  /**
+   * Called once when the instance is created (before DOM attach).
+   *
+   * @param ctx - The component context for this instance.
+   * @returns void
+   * @example
+   * onCreate({ el }) { el.dataset.ready = "1"; }
+   */
+  onCreate?(ctx: ComponentContext<S>): void;
+  /**
+   * Called after the instance is attached to its element.
+   *
+   * @param ctx - The component context for this instance.
+   * @returns void
+   * @example
+   * onMount({ el }) { el.textContent = "0"; }
+   * @example
+   * async onMount(ctx) { ctx.set({ items: await load() }); } // async is allowed; the harness awaits it via settle()
+   */
+  onMount?(ctx: ComponentContext<S>): void;
+  /**
+   * Called when a navigation begins while this instance is mounted.
+   *
+   * @param ctx - The component context for this instance.
+   * @returns void
+   * @example
+   * onNavStart({ el }) { el.dataset.loading = ""; }
+   */
+  onNavStart?(ctx: ComponentContext<S>): void;
+  /**
+   * Called when a navigation completes while this instance is mounted.
+   *
+   * @param ctx - The component context for this instance.
+   * @returns void
+   * @example
+   * onNavEnd({ el }) { delete el.dataset.loading; }
+   */
+  onNavEnd?(ctx: ComponentContext<S>): void;
+  /**
+   * Called before the instance is detached from its element.
+   *
+   * @param ctx - The component context for this instance.
+   * @returns void
+   * @example
+   * onUnMount({ el }) { el.replaceChildren(); }
+   */
+  onUnMount?(ctx: ComponentContext<S>): void;
+  /**
+   * Called once when the instance is destroyed (after detach).
+   *
+   * @param ctx - The component context for this instance.
+   * @returns void
+   * @example
+   * onDestroy({ el }) { delete el.dataset.ready; }
+   */
+  onDestroy?(ctx: ComponentContext<S>): void;
+}
+/**
+ * The spec extras carried on a {@link ComponentDef}, type-erased to `object` state
+ * (authors keep full `S` inference at the `createComponent` call site; the registry
+ * stores the runtime-only erased form). Absent for legacy `(name, hooks)` defs.
+ */
+interface ComponentSpecExtras {
+  /** Per-instance state factory. */
+  state?: ComponentStateFactory<object>;
+  /** Render called on mount + after every `ctx.set`. */
+  render?: ComponentRender<object>;
+  /** Declarative delegated events. */
+  events?: ComponentEvents<object>;
+  /** Public api factory registered under the component name. */
+  api?: (ctx: ComponentContext<object>) => unknown;
+}
+/** A registered component definition (an opaque token; author inference lives on `createComponent`). */
+interface ComponentDef {
+  /** Unique component name (matched against `data-component`). */
+  name: string;
+  /** Lifecycle hooks (the subset shared with the legacy form). */
+  hooks: ComponentHooks<object>;
+  /** Plugin-mirror extras (state/render/events/api). Absent for legacy `(name, hooks)` defs. */
+  spec?: ComponentSpecExtras;
+}
+/** The matched-route slice carried on a live instance (params/meta/locale + link builder). */
+type ComponentRouteSlice = Pick<ComponentContext, "params" | "meta" | "locale" | "url">;
+/** Page data payload parsed from the inline `script#__DATA__` element. */
+type PageData = Record<string, unknown>;
+//#endregion
+//#region src/plugins/spa/components.d.ts
+/** The matched-route slice merged onto the component context (params/meta/locale + link builder). */
+type RouteSlice = ComponentRouteSlice;
+//#endregion
+//#region src/testing.d.ts
+/** One captured spa emit (the kernel's `spa:component-mount` / `-unmount`). */
+interface CapturedEmit {
+  /** The event name. */
+  readonly event: string;
+  /** The event payload. */
+  readonly payload: unknown;
+}
+/** A mounted island a unit/integration test drives without booting `createApp`. */
+interface IslandHandle<S extends object = object, A = unknown> {
+  /** The host element the island bound to (already in `document.body`). */
+  readonly el: HTMLElement;
+  /** Live per-instance state (typed). `undefined` for legacy hooks-only islands. */
+  readonly state: S | undefined;
+  /** The island's registered api (typed), if it declared `api`. */
+  readonly api: A | undefined;
+  /**
+   * Dispatch a delegated event by spec: `fire("click [data-action='delete']")` clicks
+   * the first matching element inside the host (or the host itself when no selector).
+   *
+   * @param spec - `"<type>"` or `"<type> <selector>"` (same grammar as the `events` map).
+   * @param init - Optional event init (bubbles/cancelable are defaulted true).
+   * @example
+   * handle.fire("submit [data-create]");
+   */
+  fire(spec: string, init?: EventInit): void;
+  /**
+   * Dispatch a RAW, pre-built event at a selector — full control for events the
+   * synthetic `fire` cannot build (DragEvent/dataTransfer/clientY).
+   *
+   * @param selector - The element to dispatch on (the host when no match).
+   * @param event - The pre-constructed event.
+   * @example
+   * handle.dispatch('[data-cards]', Object.assign(new Event("drop", { bubbles: true }), { dataTransfer }));
+   */
+  dispatch(selector: string, event: Event): void;
+  /**
+   * Synchronously drain any pending render now (mutate → flush → assert, no `await`).
+   * For VNode-returning islands call {@link IslandHandle.settle} first so the lazy
+   * Preact render chunk is loaded.
+   *
+   * @example
+   * handle.flush();
+   */
+  flush(): void;
+  /**
+   * Await `onMount`'s returned promise + the render-chunk load + a microtask, then
+   * flush — the deterministic settle for async mounts and VNode renders.
+   *
+   * @returns A promise resolving once the island is fully mounted and rendered.
+   * @example
+   * await handle.settle();
+   */
+  settle(): Promise<void>;
+  /**
+   * Fire `onNavStart` on the instance (persistent + page-specific receive it).
+   *
+   * @example
+   * handle.navStart();
+   */
+  navStart(): void;
+  /**
+   * Fire `onNavEnd` on a persistent instance, with an optional destination route slice.
+   *
+   * @param route - Partial route slice to merge onto the current one.
+   * @example
+   * handle.navEnd({ params: { id: "b2" } });
+   */
+  navEnd(route?: Partial<RouteSlice>): void;
+  /**
+   * Run `onUnMount` + `onDestroy` (asserts auto-teardown of `events` + `ctx.cleanup`).
+   *
+   * @example
+   * handle.unmount();
+   */
+  unmount(): void;
+  /** Captured `spa:component-mount` / `-unmount` emits, in order. */
+  readonly emitted: ReadonlyArray<CapturedEmit>;
+}
+/** Options for {@link mountIsland}. All optional; sensible headless defaults. */
+interface MountIslandOptions {
+  /** Inner HTML placed INSIDE the host before mount (the SSR markup the island enhances). */
+  html?: string;
+  /** Mount into THIS element instead of creating one (sandbox: a real page host). */
+  el?: HTMLElement;
+  /** Route params (→ `ctx.params`). */
+  params?: Record<string, string>;
+  /** Route meta (→ `ctx.meta`). */
+  meta?: Record<string, unknown>;
+  /** Page data (→ `ctx.data`; serialized into `#__DATA__` so `extractPageData` sees it). */
+  data?: PageData;
+  /** Route locale (→ `ctx.locale`). */
+  locale?: string;
+  /** Link builder (→ `ctx.url`); defaults to `/<name>`. */
+  url?: (name: string, params?: Record<string, string>) => string;
+  /** Mount OUTSIDE the swap area so the instance is persistent (gets `onNavEnd`). */
+  persistent?: boolean;
+  /** Stubbed sibling-island apis resolved by `ctx.component(name)`. */
+  components?: Record<string, unknown>;
+}
+/**
+ * Mount ONE island headlessly through the REAL spa kernel internals under a DOM. The
+ * unit + light-integration tier: no `createApp`, no router, no network.
+ *
+ * @param definition - The component definition under test (from `createComponent`).
+ * @param options - Host HTML/element, route slice, page data, persistence, stub apis.
+ * @returns A handle exposing the instance's `state`/`api` + event/nav/flush drivers.
+ * @example
+ * const h = mountIsland(tabNav, { html: "<a></a><a></a><a></a>", persistent: true });
+ * h.navEnd({ locale: "en" });
+ * expect(h.el.querySelector("[aria-current]")).toBeTruthy();
+ */
+declare function mountIsland<S extends object = object, A = unknown>(definition: ComponentDef, options?: MountIslandOptions): IslandHandle<S, A>;
+/** The result of {@link renderIsland} — a host plus query/flush/teardown helpers. */
+interface RenderIslandResult {
+  /** The host element the view rendered into. */
+  readonly host: HTMLElement;
+  /**
+   * The host's current `innerHTML`.
+   *
+   * @returns The serialized markup.
+   * @example
+   * expect(result.html()).toContain("Alpha");
+   */
+  html(): string;
+  /**
+   * Query the host for the first element matching a selector.
+   *
+   * @param selector - A CSS selector.
+   * @returns The first match, or `null`.
+   * @example
+   * result.find("[data-board]");
+   */
+  find<E extends Element = Element>(selector: string): E | null;
+  /**
+   * Unmount the Preact tree and remove the host from the document.
+   *
+   * @example
+   * result.unmount();
+   */
+  unmount(): void;
+}
+/**
+ * The cheapest unit tier: render a controller/view island's pure `render(state, ctx)`
+ * against fixture state, with no kernel and no `mountIsland`. Uses `preact/test-utils`
+ * `act` (which ships WITH Preact — no new dependency) so effects flush deterministically.
+ *
+ * @param render - The island's `render` function (e.g. `boardList.spec.render`).
+ * @param input - Fixture inputs.
+ * @param input.state - The fixture per-instance state to render.
+ * @param input.ctx - Optional partial context overrides.
+ * @returns A {@link RenderIslandResult} for asserting the rendered DOM.
+ * @example
+ * const r = renderIsland(render, { state: { boards: [{ id: "1", title: "Alpha" }] } });
+ * expect(r.find("[data-board]")).toBeTruthy();
+ */
+declare function renderIsland<S extends object>(render: ComponentRender<S>, input: {
+  state: S;
+  ctx?: Partial<ComponentContext<S>>;
+}): RenderIslandResult;
+//#endregion
+export { CapturedEmit, IslandHandle, MountIslandOptions, RenderIslandResult, mountIsland, renderIsland };