@moku-labs/web 1.13.2 → 1.15.0

package/dist/index.d.cts

@@ -231,6 +231,28 @@ type Api$6 = {
   t(locale: string, key: string): string;
 };
 //#endregion
+//#region src/plugins/i18n/index.d.ts
+/**
+ * Internationalization plugin — locale registry plus a flat translation helper
+ * with default-locale fallback. Pure config-as-data (no state or events);
+ * consumed read-only by content, router, head, and build.
+ *
+ * @example Register locales and translations
+ * ```ts
+ * const app = createApp({
+ *   pluginConfigs: {
+ *     i18n: {
+ *       locales: ["en", "uk"],
+ *       defaultLocale: "en",
+ *       localeNames: { en: "English", uk: "Українська" },
+ *       translations: { uk: { "nav.home": "Головна" } }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const i18nPlugin: import("@moku-labs/core").PluginInstance<"i18n", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>;
+//#endregion
 //#region src/plugins/router/iso-match.d.ts
 /**
  * A compiled, engine-agnostic path matcher: the same `.exec({ pathname })` shape the
@@ -288,7 +310,10 @@ interface RouteState<P extends string = string, D = unknown> {
   /** Loaded data type produced by `.load()` (widened only by `.load()`). */
   readonly data: D;
 }
-/** Render-time context handed to `.render()` / `.head()`; `data` is `.load()`'s return. */
+/**
+ * Render-time context handed to `.render()` / `.head()`; `data` is `.load()`'s return,
+ * `meta` the route's `.meta()` bag.
+ */
 interface RouteContext<S extends RouteState> {
   /** Resolved path params. */
   readonly params: S["params"];
@@ -296,6 +321,13 @@ interface RouteContext<S extends RouteState> {
   readonly data: S["data"];
   /** Active locale for this render. */
   readonly locale: string;
+  /**
+   * The route's `.meta()` bag (e.g. `{ activeTab: "home" }`). Available in `.render()` and
+   * `.head()`, identically at build and on the client — `meta` is compiled into the route and
+   * shipped in the client manifest, so a client-only route (dynamic, no `.generate()`, whose
+   * `.load()` data is `{}` on the client) can feed static per-route config into its render.
+   */
+  readonly meta: Record<string, unknown>;
   /**
    * Build a link to a named route by pattern substitution — the framework delivers
    * this on the context (same output as `app.router.toUrl`), so render/head build
@@ -376,21 +408,16 @@ interface GenerateContext {
   readonly has: (name: string) => boolean;
 }
 /**
- * Context handed to a route's `.layout()` wrapper: the render-time
- * {@link RouteContext} plus the route's `.meta()` bag, so persistent chrome (e.g. a
- * TopBar/TabNav) can read `locale` and `meta.activeTab`. Distinct from
- * `RouteContext` because the layout is the only handler that needs `meta`; keeping
- * it on its own type leaves `.render()`/`.head()` contexts unchanged.
+ * Context handed to a route's `.layout()` wrapper — identical to {@link RouteContext}
+ * (which now carries `meta` for every handler). Retained as a named alias so existing
+ * `.layout((ctx, children) => …)` typings keep compiling.
  *
  * @remarks
  * The layout is applied in the SSG render path ONLY. On client (SPA) navigation the
- * chrome is persistent and the layout is intentionally NOT re-applied — only the
- * inner swap region is replaced. See `build`'s pages phase and `spa`'s kernel.
+ * chrome is persistent and the layout is intentionally NOT re-applied — only the inner
+ * swap region is replaced. See `build`'s pages phase and `spa`'s kernel.
  */
-interface LayoutContext<S extends RouteState> extends RouteContext<S> {
-  /** The route's `.meta()` bag (e.g. `{ activeTab: "home" }`). */
-  readonly meta: Record<string, unknown>;
-}
+type LayoutContext<S extends RouteState> = RouteContext<S>;
 /** Head metadata produced by a route's `.head()` handler. */
 interface HeadConfig$1 {
   /** Document title. */
@@ -945,12 +972,25 @@ interface ResolvedSpaConfig {
   /** Pre-registered components. */
   components: ComponentDef[];
 }
-/** Context handed to every component lifecycle hook. */
+/**
+ * Context handed to every component lifecycle hook — 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.
+ */
 interface ComponentContext {
   /** 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;
 }
 /** Lifecycle hooks a component may implement. */
 interface ComponentHooks {
@@ -1234,7 +1274,7 @@ type PhaseContext = {
   readonly global: Readonly<{
     stage: Stage;
   }>; /** Resolve a depended-upon plugin instance to its public API. */
-  require: PhaseRequire; /** Whether a plugin is registered (by name) — used to detect the OPTIONAL `data` plugin. */
+  require: PhaseRequire; /** Whether a plugin is registered (by name) — used to detect OPTIONAL plugins (`data`, `content`, `i18n`, `head`). */
   has: (name: string) => boolean; /** Emit a build event (notification-only). */
   emit: PhaseEmit; /** Structured logger (core `log` API). */
   readonly log: PhaseLog;
@@ -1567,7 +1607,8 @@ type Api$3 = {
 /**
  * Build plugin — the static-site-generation orchestrator. Renders every route to
  * `outDir`, and optionally emits feeds, a sitemap, optimized images, and OG
- * images. Depends on site, i18n, content, router, and head; emits `build:phase`.
+ * images. Hard-depends only on site, router, and head; `content` and `i18n` are
+ * OPTIONAL (a content-less or single-locale site builds without them). Emits `build:phase`.
  *
  * @example Configure the production build
  * ```ts
@@ -2817,7 +2858,8 @@ type Api = {
  * (locale fallback, draft filtering, sort, caching, events) lives here; source I/O +
  * the Markdown pipeline live in a {@link ContentProvider} you compose (like `env`
  * providers). The shell imports zero node code, so `contentPlugin` is browser-safe.
- * Depends on i18n; emits `content:ready` and `content:invalidated`.
+ * i18n is OPTIONAL (single default-locale fallback when absent); emits `content:ready`
+ * and `content:invalidated`.
  *
  * @example Compose the node filesystem provider with a content dir + Shiki theme
  * ```ts
@@ -3109,7 +3151,7 @@ declare function buildArticleHead(articleMeta: ArticleMeta, canonicalUrl: string
  * Head plugin — composes per-route `<head>` metadata (title template, Open Graph,
  * Twitter cards, canonical, hreflang). Use the re-exported SEO primitives
  * ({@link meta}, {@link og}, {@link twitter}, …) inside a route's `.head()`.
- * Depends on site, i18n, and router.
+ * Depends on site and router; i18n is OPTIONAL (single default-locale fallback when absent).
  *
  * @example Set global head defaults
  * ```ts
@@ -3135,28 +3177,6 @@ declare const headPlugin: import("@moku-labs/core").PluginInstance<"head", Confi
   buildArticleHead: typeof buildArticleHead;
 };
 //#endregion
-//#region src/plugins/i18n/index.d.ts
-/**
- * Internationalization plugin — locale registry plus a flat translation helper
- * with default-locale fallback. Pure config-as-data (no state or events);
- * consumed read-only by content, router, head, and build.
- *
- * @example Register locales and translations
- * ```ts
- * const app = createApp({
- *   pluginConfigs: {
- *     i18n: {
- *       locales: ["en", "uk"],
- *       defaultLocale: "en",
- *       localeNames: { en: "English", uk: "Українська" },
- *       translations: { uk: { "nav.home": "Головна" } }
- *     }
- *   }
- * });
- * ```
- */
-declare const i18nPlugin: import("@moku-labs/core").PluginInstance<"i18n", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>;
-//#endregion
 //#region src/plugins/router/builders/route-builder.d.ts
 /**
  * Create a fluent route builder from a URL pattern string. Captures the pattern
@@ -3220,8 +3240,8 @@ declare function createUrls<T extends RouteMap>(routes: T, defaultLocale?: strin
 /**
  * Router plugin — typed, named route definitions with locale-aware URL generation
  * and matching. Author routes with {@link route}, then register them the normal config
- * way via `pluginConfigs.router.routes` (compiled at init). Depends on site (base URL)
- * and i18n (locales).
+ * way via `pluginConfigs.router.routes` (compiled at init). Depends on site (base URL);
+ * i18n (locales) is OPTIONAL — falls back to a single default locale ("en") when absent.
  *
  * @example Register routes via config, then start/build
  * ```ts

package/dist/index.d.mts

@@ -229,6 +229,28 @@ type Api$6 = {
   t(locale: string, key: string): string;
 };
 //#endregion
+//#region src/plugins/i18n/index.d.ts
+/**
+ * Internationalization plugin — locale registry plus a flat translation helper
+ * with default-locale fallback. Pure config-as-data (no state or events);
+ * consumed read-only by content, router, head, and build.
+ *
+ * @example Register locales and translations
+ * ```ts
+ * const app = createApp({
+ *   pluginConfigs: {
+ *     i18n: {
+ *       locales: ["en", "uk"],
+ *       defaultLocale: "en",
+ *       localeNames: { en: "English", uk: "Українська" },
+ *       translations: { uk: { "nav.home": "Головна" } }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const i18nPlugin: import("@moku-labs/core").PluginInstance<"i18n", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>;
+//#endregion
 //#region src/plugins/router/iso-match.d.ts
 /**
  * A compiled, engine-agnostic path matcher: the same `.exec({ pathname })` shape the
@@ -286,7 +308,10 @@ interface RouteState<P extends string = string, D = unknown> {
   /** Loaded data type produced by `.load()` (widened only by `.load()`). */
   readonly data: D;
 }
-/** Render-time context handed to `.render()` / `.head()`; `data` is `.load()`'s return. */
+/**
+ * Render-time context handed to `.render()` / `.head()`; `data` is `.load()`'s return,
+ * `meta` the route's `.meta()` bag.
+ */
 interface RouteContext<S extends RouteState> {
   /** Resolved path params. */
   readonly params: S["params"];
@@ -294,6 +319,13 @@ interface RouteContext<S extends RouteState> {
   readonly data: S["data"];
   /** Active locale for this render. */
   readonly locale: string;
+  /**
+   * The route's `.meta()` bag (e.g. `{ activeTab: "home" }`). Available in `.render()` and
+   * `.head()`, identically at build and on the client — `meta` is compiled into the route and
+   * shipped in the client manifest, so a client-only route (dynamic, no `.generate()`, whose
+   * `.load()` data is `{}` on the client) can feed static per-route config into its render.
+   */
+  readonly meta: Record<string, unknown>;
   /**
    * Build a link to a named route by pattern substitution — the framework delivers
    * this on the context (same output as `app.router.toUrl`), so render/head build
@@ -374,21 +406,16 @@ interface GenerateContext {
   readonly has: (name: string) => boolean;
 }
 /**
- * Context handed to a route's `.layout()` wrapper: the render-time
- * {@link RouteContext} plus the route's `.meta()` bag, so persistent chrome (e.g. a
- * TopBar/TabNav) can read `locale` and `meta.activeTab`. Distinct from
- * `RouteContext` because the layout is the only handler that needs `meta`; keeping
- * it on its own type leaves `.render()`/`.head()` contexts unchanged.
+ * Context handed to a route's `.layout()` wrapper — identical to {@link RouteContext}
+ * (which now carries `meta` for every handler). Retained as a named alias so existing
+ * `.layout((ctx, children) => …)` typings keep compiling.
  *
  * @remarks
  * The layout is applied in the SSG render path ONLY. On client (SPA) navigation the
- * chrome is persistent and the layout is intentionally NOT re-applied — only the
- * inner swap region is replaced. See `build`'s pages phase and `spa`'s kernel.
+ * chrome is persistent and the layout is intentionally NOT re-applied — only the inner
+ * swap region is replaced. See `build`'s pages phase and `spa`'s kernel.
  */
-interface LayoutContext<S extends RouteState> extends RouteContext<S> {
-  /** The route's `.meta()` bag (e.g. `{ activeTab: "home" }`). */
-  readonly meta: Record<string, unknown>;
-}
+type LayoutContext<S extends RouteState> = RouteContext<S>;
 /** Head metadata produced by a route's `.head()` handler. */
 interface HeadConfig$1 {
   /** Document title. */
@@ -943,12 +970,25 @@ interface ResolvedSpaConfig {
   /** Pre-registered components. */
   components: ComponentDef[];
 }
-/** Context handed to every component lifecycle hook. */
+/**
+ * Context handed to every component lifecycle hook — 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.
+ */
 interface ComponentContext {
   /** 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;
 }
 /** Lifecycle hooks a component may implement. */
 interface ComponentHooks {
@@ -1232,7 +1272,7 @@ type PhaseContext = {
   readonly global: Readonly<{
     stage: Stage;
   }>; /** Resolve a depended-upon plugin instance to its public API. */
-  require: PhaseRequire; /** Whether a plugin is registered (by name) — used to detect the OPTIONAL `data` plugin. */
+  require: PhaseRequire; /** Whether a plugin is registered (by name) — used to detect OPTIONAL plugins (`data`, `content`, `i18n`, `head`). */
   has: (name: string) => boolean; /** Emit a build event (notification-only). */
   emit: PhaseEmit; /** Structured logger (core `log` API). */
   readonly log: PhaseLog;
@@ -1565,7 +1605,8 @@ type Api$3 = {
 /**
  * Build plugin — the static-site-generation orchestrator. Renders every route to
  * `outDir`, and optionally emits feeds, a sitemap, optimized images, and OG
- * images. Depends on site, i18n, content, router, and head; emits `build:phase`.
+ * images. Hard-depends only on site, router, and head; `content` and `i18n` are
+ * OPTIONAL (a content-less or single-locale site builds without them). Emits `build:phase`.
  *
  * @example Configure the production build
  * ```ts
@@ -2815,7 +2856,8 @@ type Api = {
  * (locale fallback, draft filtering, sort, caching, events) lives here; source I/O +
  * the Markdown pipeline live in a {@link ContentProvider} you compose (like `env`
  * providers). The shell imports zero node code, so `contentPlugin` is browser-safe.
- * Depends on i18n; emits `content:ready` and `content:invalidated`.
+ * i18n is OPTIONAL (single default-locale fallback when absent); emits `content:ready`
+ * and `content:invalidated`.
  *
  * @example Compose the node filesystem provider with a content dir + Shiki theme
  * ```ts
@@ -3107,7 +3149,7 @@ declare function buildArticleHead(articleMeta: ArticleMeta, canonicalUrl: string
  * Head plugin — composes per-route `<head>` metadata (title template, Open Graph,
  * Twitter cards, canonical, hreflang). Use the re-exported SEO primitives
  * ({@link meta}, {@link og}, {@link twitter}, …) inside a route's `.head()`.
- * Depends on site, i18n, and router.
+ * Depends on site and router; i18n is OPTIONAL (single default-locale fallback when absent).
  *
  * @example Set global head defaults
  * ```ts
@@ -3133,28 +3175,6 @@ declare const headPlugin: import("@moku-labs/core").PluginInstance<"head", Confi
   buildArticleHead: typeof buildArticleHead;
 };
 //#endregion
-//#region src/plugins/i18n/index.d.ts
-/**
- * Internationalization plugin — locale registry plus a flat translation helper
- * with default-locale fallback. Pure config-as-data (no state or events);
- * consumed read-only by content, router, head, and build.
- *
- * @example Register locales and translations
- * ```ts
- * const app = createApp({
- *   pluginConfigs: {
- *     i18n: {
- *       locales: ["en", "uk"],
- *       defaultLocale: "en",
- *       localeNames: { en: "English", uk: "Українська" },
- *       translations: { uk: { "nav.home": "Головна" } }
- *     }
- *   }
- * });
- * ```
- */
-declare const i18nPlugin: import("@moku-labs/core").PluginInstance<"i18n", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>;
-//#endregion
 //#region src/plugins/router/builders/route-builder.d.ts
 /**
  * Create a fluent route builder from a URL pattern string. Captures the pattern
@@ -3218,8 +3238,8 @@ declare function createUrls<T extends RouteMap>(routes: T, defaultLocale?: strin
 /**
  * Router plugin — typed, named route definitions with locale-aware URL generation
  * and matching. Author routes with {@link route}, then register them the normal config
- * way via `pluginConfigs.router.routes` (compiled at init). Depends on site (base URL)
- * and i18n (locales).
+ * way via `pluginConfigs.router.routes` (compiled at init). Depends on site (base URL);
+ * i18n (locales) is OPTIONAL — falls back to a single default locale ("en") when absent.
  *
  * @example Register routes via config, then start/build
  * ```ts