@moku-labs/web 1.0.0 → 1.0.1

package/README.md

@@ -15,7 +15,7 @@ Built on the [@moku-labs/core](https://github.com/moku-labs/core) micro-kernel
 [![CI](https://github.com/moku-labs/web/actions/workflows/ci.yml/badge.svg)](https://github.com/moku-labs/web/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@moku-labs/web?logo=npm&color=cb3837&label=npm)](https://www.npmjs.com/package/@moku-labs/web)
 [![types](https://img.shields.io/badge/types-included-3178c6?logo=typescript&logoColor=white)](#requirements)
-[![browser bundle](https://img.shields.io/badge/browser%20entry-~41%20kB%20gzip-2da44e)](#the-browser-entry-is-guaranteed-node-free)
+[![browser bundle](https://img.shields.io/badge/browser%20entry-~45%20kB%20gzip-2da44e)](#the-browser-entry-is-guaranteed-node-free)
 [![node](https://img.shields.io/badge/node-%3E%3D24-339933?logo=node.js&logoColor=white)](#requirements)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
@@ -45,7 +45,7 @@ bun add @moku-labs/web
 - **SSG first, SPA when you want it.** Render [Preact](https://preactjs.com) pages to static HTML for SEO and instant first paint, then progressively enhance with island hydration and client-side navigation — opt in per project with a single switch.
 - **The route is the contract.** One typed `route()` builder owns `load` → `render` → `head`. The build and the client run the *same* `render`, so there's no second code path to keep in sync. [Jump to the example ↓](#the-route-is-the-contract)
 - **SEO complete out of the box.** Title templates, canonical + `hreflang`, Open Graph / Twitter cards, JSON-LD, RSS / Atom / JSON feeds, `sitemap.xml`, and generated OG images.
-- **The `/browser` entry is guaranteed node-free.** A dedicated client entry whose static import graph references *zero* node modules — native code can never leak into your bundle, no matter your bundler or tree-shaking. A CI gate keeps it under budget (~41 kB gzip today). [Why this matters ↓](#the-browser-entry-is-guaranteed-node-free)
+- **The `/browser` entry is guaranteed node-free.** A dedicated client entry whose static import graph references *zero* node modules — native code can never leak into your bundle, no matter your bundler or tree-shaking. A CI gate keeps it under budget (~45 kB gzip today). [Why this matters ↓](#the-browser-entry-is-guaranteed-node-free)
 - **Plugins all the way down.** A tiny isomorphic core (`site`, `i18n`, `router`, `head`, `spa`) plus opt-in node-only plugins (`content`, `build`, `deploy`, `cli`), each [independently documented](#plugins) and composed in one `createApp` call.
 - **Types do the heavy lifting.** `ctx.data` is inferred from your `.load()`, path params from the route pattern, plugin APIs from their specs — no codegen, no `as`.
 - **i18n is built in.** Locale-aware routes, default-locale fallback, `hreflang` / `og:locale` maps.

package/dist/browser.mjs

@@ -375,6 +375,40 @@ function isPlainObject$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
+* Tests whether `actual` is an array that recursively matches every element of
+* the `partial` array (element-wise, with equal length).
+*
+* @param actual - The value to test against (must be an array of equal length).
+* @param partial - The expected partial array shape.
+* @returns `true` when `actual` is an equal-length array matching `partial` element-wise.
+* @example
+* ```ts
+* matchesPartialArray([1, 2], [1, 2]); // true
+* matchesPartialArray([1], [1, 2]); // false (length mismatch)
+* ```
+*/
+function matchesPartialArray(actual, partial) {
+	if (!Array.isArray(actual) || actual.length !== partial.length) return false;
+	return partial.every((value, index) => matchesPartial(actual[index], value));
+}
+/**
+* Tests whether `actual` is a plain object in which every `partial` key
+* recursively matches (extra `actual` keys are ignored).
+*
+* @param actual - The value to test against (must be a plain object).
+* @param partial - The expected partial object shape.
+* @returns `true` when every `partial` key exists in `actual` and matches recursively.
+* @example
+* ```ts
+* matchesPartialObject({ a: 1, b: 2 }, { a: 1 }); // true
+* matchesPartialObject({ a: 1 }, { b: 1 }); // false (missing key)
+* ```
+*/
+function matchesPartialObject(actual, partial) {
+	if (!isPlainObject$1(actual)) return false;
+	return Object.keys(partial).every((key) => key in actual && matchesPartial(actual[key], partial[key]));
+}
+/**
 * Subset-equality matcher: is `partial` a recursive subset of `actual`?
 *
 * Fast path via `Object.is` (covers identical primitives/references and
@@ -393,14 +427,8 @@ function isPlainObject$1(value) {
 */
 function matchesPartial(actual, partial) {
 	if (Object.is(actual, partial)) return true;
-	if (Array.isArray(partial)) {
-		if (!Array.isArray(actual) || actual.length !== partial.length) return false;
-		return partial.every((value, index) => matchesPartial(actual[index], value));
-	}
-	if (isPlainObject$1(partial)) {
-		if (!isPlainObject$1(actual)) return false;
-		return Object.keys(partial).every((key) => key in actual && matchesPartial(actual[key], partial[key]));
-	}
+	if (Array.isArray(partial)) return matchesPartialArray(actual, partial);
+	if (isPlainObject$1(partial)) return matchesPartialObject(actual, partial);
 	return false;
 }
 /**
@@ -1417,6 +1445,25 @@ function hasValidLangCount(pattern) {
 	return (pattern.match(/\{lang:\?\}/g) ?? []).length <= MAX_LANG_SEGMENTS;
 }
 /**
+* Assert a single route's pattern is well-formed, throwing the `[web]`-prefixed
+* error for the first failure: not rooted at `/`, unbalanced `{…}` braces, or
+* more than one `{lang:?}` segment. Extracted from {@link validateRoutes} so the
+* loop body stays flat.
+*
+* @param name - The route name key, surfaced in any error message.
+* @param pattern - The route's user pattern to validate.
+* @throws {Error} When the pattern is malformed.
+* @example
+* ```ts
+* assertRouteValid("home", "/{slug}/");
+* ```
+*/
+function assertRouteValid(name, pattern) {
+	if (!isPatternRooted(pattern)) throw new Error(`${ERROR_PREFIX$6}: route "${name}" pattern must start with "/" (got "${pattern}").`);
+	if (!hasBalancedBraces(pattern)) throw new Error(`${ERROR_PREFIX$6}: route "${name}" pattern has unbalanced braces ("${pattern}").`);
+	if (!hasValidLangCount(pattern)) throw new Error(`${ERROR_PREFIX$6}: route "${name}" pattern has more than one {lang:?} segment ("${pattern}").`);
+}
+/**
 * Validate the route map (fail-fast in `onInit`). Throws with the `[web]` prefix
 * naming the offending route/pattern on any failure: empty map, a pattern not
 * starting with `/`, unbalanced `{…}` braces, or more than one `{lang:?}` segment.
@@ -1431,12 +1478,7 @@ function hasValidLangCount(pattern) {
 function validateRoutes(routes) {
 	const names = Object.keys(routes);
 	if (names.length === 0) throw new Error(`${ERROR_PREFIX$6}: route map is empty.\n  Register at least one route via pluginConfigs.router.routes.`);
-	for (const name of names) {
-		const pattern = routes[name]?.pattern ?? "";
-		if (!isPatternRooted(pattern)) throw new Error(`${ERROR_PREFIX$6}: route "${name}" pattern must start with "/" (got "${pattern}").`);
-		if (!hasBalancedBraces(pattern)) throw new Error(`${ERROR_PREFIX$6}: route "${name}" pattern has unbalanced braces ("${pattern}").`);
-		if (!hasValidLangCount(pattern)) throw new Error(`${ERROR_PREFIX$6}: route "${name}" pattern has more than one {lang:?} segment ("${pattern}").`);
-	}
+	for (const name of names) assertRouteValid(name, routes[name]?.pattern ?? "");
 }
 /**
 * Convert a user pattern to a `URLPattern` source string, in a `withLang` or
@@ -2990,6 +3032,22 @@ const ERROR_PREFIX$2 = "[web]";
 /** The set of legal hook names, frozen for O(1) membership checks. */
 const HOOK_NAME_SET = new Set(COMPONENT_HOOK_NAMES);
 /**
+* Validate a single hook entry: its key must be a known hook name and its value
+* must be a function. Throws fail-fast on the first violation.
+*
+* @param componentName - The owning component name (for error messages).
+* @param hooks - The hooks object being validated.
+* @param key - The hook key to validate.
+* @throws {Error} If `key` is not in `COMPONENT_HOOK_NAMES`.
+* @throws {TypeError} If the hook value is not a function.
+* @example
+* validateHookEntry("counter", hooks, "onMount");
+*/
+function validateHookEntry(componentName, hooks, key) {
+	if (!HOOK_NAME_SET.has(key)) throw new Error(`${ERROR_PREFIX$2} unknown component hook "${key}" on "${componentName}"\n  → valid hooks: ${COMPONENT_HOOK_NAMES.join(", ")}`);
+	if (typeof hooks[key] !== "function") throw new TypeError(`${ERROR_PREFIX$2} component hook "${key}" on "${componentName}" must be a function\n  → provide a function or omit the hook`);
+}
+/**
 * Create a validated component definition. Validates hook names at registration
 * for fail-fast typo detection (e.g. `onMout` throws immediately) and asserts
 * each provided hook is a function.
@@ -3006,10 +3064,7 @@ const HOOK_NAME_SET = new Set(COMPONENT_HOOK_NAMES);
 */
 function createComponent(name, hooks) {
 	if (name.trim() === "") throw new Error(`${ERROR_PREFIX$2} component name must be a non-empty string\n  → pass a unique name to createComponent("name", hooks)`);
-	for (const key of Object.keys(hooks)) {
-		if (!HOOK_NAME_SET.has(key)) throw new Error(`${ERROR_PREFIX$2} unknown component hook "${key}" on "${name}"\n  → valid hooks: ${COMPONENT_HOOK_NAMES.join(", ")}`);
-		if (typeof hooks[key] !== "function") throw new TypeError(`${ERROR_PREFIX$2} component hook "${key}" on "${name}" must be a function\n  → provide a function or omit the hook`);
-	}
+	for (const key of Object.keys(hooks)) validateHookEntry(name, hooks, key);
 	return {
 		name,
 		hooks
@@ -3079,6 +3134,36 @@ function makeContext(element, data) {
 	};
 }
 /**
+* Mounts a single `data-component` element: classifies persistent vs
+* page-specific, builds the instance, fires `onCreate` then `onMount`, records
+* it in state, and emits `spa:component-mount`. No-ops if the element is already
+* mounted, has no component name, or names an unregistered component.
+*
+* @param state - The plugin state (registeredComponents + instances).
+* @param emit - The event emitter for spa:component-mount.
+* @param swapArea - The swap-region element, or null when none was found.
+* @param data - The current page data payload.
+* @param element - The candidate element carrying a `data-component` attribute.
+* @example
+* mountElement(state, emit, swapArea, data, element);
+*/
+function mountElement(state, emit, swapArea, data, element) {
+	if (state.instances.has(element)) return;
+	const name = element.dataset.component;
+	if (!name) return;
+	const definition = state.registeredComponents.get(name);
+	if (!definition) return;
+	const instance = createInstance(definition, element, swapArea ? !swapArea.contains(element) : true);
+	const ctx = makeContext(element, data);
+	runHook(instance, "onCreate", ctx);
+	runHook(instance, "onMount", ctx);
+	state.instances.set(element, instance);
+	emit("spa:component-mount", {
+		name: definition.name,
+		el: element
+	});
+}
+/**
 * Scans the swap region, mounts components for matching `data-component`
 * elements, classifies persistent (outside swap area) vs page-specific (inside),
 * fires `onCreate` then `onMount`, and emits `spa:component-mount` per instance.
@@ -3094,22 +3179,7 @@ function scanAndMount(state, emit, swapSelector) {
 	if (typeof document === "undefined") return;
 	const swapArea = document.querySelector(swapSelector);
 	const data = extractPageData(document);
-	for (const element of document.querySelectorAll("[data-component]")) {
-		if (state.instances.has(element)) continue;
-		const name = element.dataset.component;
-		if (!name) continue;
-		const definition = state.registeredComponents.get(name);
-		if (!definition) continue;
-		const instance = createInstance(definition, element, swapArea ? !swapArea.contains(element) : true);
-		const ctx = makeContext(element, data);
-		runHook(instance, "onCreate", ctx);
-		runHook(instance, "onMount", ctx);
-		state.instances.set(element, instance);
-		emit("spa:component-mount", {
-			name: definition.name,
-			el: element
-		});
-	}
+	for (const element of document.querySelectorAll("[data-component]")) mountElement(state, emit, swapArea, data, element);
 }
 /**
 * Unmounts page-specific instances inside the swap region (runs `onUnMount`
@@ -3580,6 +3650,8 @@ function attachRouter(handlers, navigate) {
 //#region src/plugins/spa/state.ts
 /** Error prefix for spa config-validation failures (spec/11 Part-3). */
 const ERROR_PREFIX$1 = "[web]";
+/** Last-resort `swapSelector` when neither config nor defaults supply one. */
+const FALLBACK_SWAP_SELECTOR = "main > section";
 /** Default SPA config (declared as a value — no inline assertion). */
 const defaultSpaConfig = {
 	swapSelector: "main > section",
@@ -3617,7 +3689,7 @@ function isValidSelector(selector) {
 * const resolved = resolveSpaConfig({ swapSelector: "main > section" });
 */
 function resolveSpaConfig(config) {
-	const swapSelector = config.swapSelector ?? defaultSpaConfig.swapSelector ?? "main > section";
+	const swapSelector = config.swapSelector ?? defaultSpaConfig.swapSelector ?? FALLBACK_SWAP_SELECTOR;
 	if (swapSelector.trim() === "") throw new Error(`${ERROR_PREFIX$1} spa.swapSelector must be a non-empty string.\n  Set a CSS selector for the page region to swap (e.g. "main > section").`);
 	if (!isValidSelector(swapSelector)) throw new Error(`${ERROR_PREFIX$1} spa.swapSelector is not a valid CSS selector: "${swapSelector}".\n  Provide a syntactically valid selector.`);
 	return {