@moku-labs/web 2.0.1 → 2.1.0

package/dist/testing.d.mts

@@ -1,12 +1,32 @@
+//#region src/plugins/router/types.d.ts
+/**
+ * Scroll behaviour for a navigation TO a route — a closed, typed vocabulary the SPA
+ * kernel interprets (a first-class `.scroll()` method, not a `.meta()` key):
+ * - `"top"` — reset to the top of the page on the swap (the default for forward navs);
+ * - `"preserve"` — keep the current scroll position (e.g. opening an overlay/issue route
+ *   over a board that must stay still). A route's `.scroll()` OVERRIDES `spa.scrollRestoration`.
+ */
+type ScrollMode = "top" | "preserve";
+//#endregion
 //#region src/plugins/spa/types.d.ts
+/** Per-navigation options for the programmatic navigators (`ctx.navigate` / `app.spa.navigate`). */
+interface NavigateOptions {
+  /** Override the scroll behaviour for this single navigation (else the route/app default). */
+  scroll?: ScrollMode;
+}
 /**
  * What a island'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`;
+ * - `null` — render NOTHING but stay mountable: the host's Preact tree is unmounted via
+ *   `render(null, host)` (NOT `innerHTML = ""`), so a later non-empty render re-commits
+ *   cleanly. This is the correct "empty" for a persistent render-island (e.g. a closed
+ *   overlay panel) — returning `""` instead corrupts Preact's retained vdom and the panel
+ *   never re-opens;
  * - `void`/`undefined` — the render mutated the DOM itself (DOM-only islands → no Preact loaded).
  */
-type RenderResult = AnyVNode | Node | string | void;
+type RenderResult = AnyVNode | Node | string | null | void;
 /**
  * A Preact `VNode` of ANY props shape. A render returns `h(Component, props)`, i.e. a
  * `VNode<SomeProps>`; the props generic is invariant under `exactOptionalPropertyTypes`,
@@ -92,6 +112,21 @@ interface IslandContext<S = undefined> {
   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;
+  /**
+   * Programmatically navigate the SPA to an internal path (same swap pipeline as a
+   * link click; no-op without a DOM). Build `path` from the route map's `urls`/`ctx.url`,
+   * never a literal. Pass `{ scroll: "preserve" }` to keep the current scroll for this nav.
+   *
+   * An ALWAYS-PRESENT member (like `set`/`flush`/`cleanup`) so every island can navigate
+   * without an `app` handle — no synthesized anchor click.
+   *
+   * @param path - The internal destination path (e.g. `ctx.url("board", { id })`).
+   * @param options - Optional per-navigation overrides (e.g. `{ scroll: "preserve" }`).
+   * @returns void
+   * @example
+   * ctx.navigate(ctx.url("issue", { id, issueId }));
+   */
+  readonly navigate: (path: string, options?: NavigateOptions) => void;
   /** The live per-instance state (the object returned by `spec.state`). `undefined` for legacy hooks-only islands. */
   readonly state: S;
   /**

package/dist/testing.mjs

@@ -62,13 +62,15 @@ let commitVNodeFunction;
 * await loadRenderChunk();
 */
 async function loadRenderChunk() {
-	renderChunk ??= import("./render-yXHc9BWI.mjs");
+	renderChunk ??= import("./render-CkdqOmsm.mjs");
 	commitVNodeFunction = (await renderChunk).commitVNode;
 }
 /**
 * Commit a {@link RenderResult} into a host: `string` → `innerHTML`, `Node` →
-* `replaceChildren`, `void`/`undefined` → no-op (the render mutated the DOM itself), and
-* a Preact `VNode` → committed through the lazy gate (loading it on demand if needed).
+* `replaceChildren`, `null` → Preact unmount via the lazy gate (`render(null, host)` —
+* stays re-mountable, the correct "empty" for a persistent render-island), `void`/`undefined`
+* → no-op (the render mutated the DOM itself), and a Preact `VNode` → committed through the
+* lazy gate (loading it on demand if needed).
 *
 * @param host - The island host element to render into.
 * @param result - The value returned by the island's `render`.
@@ -195,6 +197,18 @@ function buildContext(state, instance) {
 			return instance.route.url;
 		},
 		/**
+		* Programmatically navigate the SPA (delegates to the kernel's navigator through
+		* `state.navigate` — the same decoupled seam as `island`). No-op before the kernel binds.
+		*
+		* @param path - The internal destination path.
+		* @param options - Optional per-navigation overrides (e.g. `{ scroll: "preserve" }`).
+		* @example
+		* ctx.navigate(ctx.url("issue", { id, issueId }));
+		*/
+		navigate(path, options) {
+			state.navigate?.(path, options);
+		},
+		/**
 		* The live per-instance state (`undefined` for legacy hooks-only islands).
 		*
 		* @returns The current state.
@@ -552,6 +566,7 @@ function createState(_ctx) {
 		currentUrl: "",
 		destroyRouter: null,
 		started: false,
+		navigate: null,
 		kernel: null
 	};
 }

package/package.json

@@ -132,5 +132,5 @@
     "test:build-e2e": "bun test src/plugins/build/__tests__/e2e/",
     "test:coverage": "vitest run --project unit --project integration --coverage"
   },
-  "version": "2.0.1"
+  "version": "2.1.0"
 }