sibujs 4.12.0 → 4.13.1

package/dist/plugins.d.cts

@@ -1,8 +1,8 @@
+export { L as LazyModule, M as Migration, a as MigrationStorageError, P as PackageExportTarget, S as SemVer, V as VERSION, b as bundlerMetadata, c as checkCompatibility, d as compareSemVer, e as createBootSequence, f as createBundle, g as createMigrationRunner, h as createModuleRegistry, i as createSSRCache, j as createTestHarness, k as deferNonCritical, l as env, m as healthCheck, n as lazyModule, p as packageInfo, o as parseSemVer, q as preloadCritical, r as prerenderRoutes, s as satisfies } from './startup-BLfSeL15.cjs';
 import { A as Accessor } from './signal-EotCj4hS.cjs';
+export { P as PluginContext, a as PluginInstallCancelledError, b as PluginRegistry, S as SibuPlugin, c as createPlugin, d as createPluginRegistry, i as inject, e as isPluginInstallCancelledError, p as plugin, r as resetPlugins, s as setDefaultPluginRegistry, t as triggerPluginError, f as triggerPluginMount, g as triggerPluginUnmount } from './plugin-DVgSnTfK.cjs';
 import { C as Component$1, N as NodeChildren } from './types-CJFViL6Q.cjs';
 import { T as TrustedHTML } from './ssr-Db0Sgdu3.cjs';
-export { P as PluginContext, a as PluginInstallCancelledError, b as PluginRegistry, S as SibuPlugin, c as createPlugin, d as createPluginRegistry, i as inject, e as isPluginInstallCancelledError, p as plugin, r as resetPlugins, s as setDefaultPluginRegistry, t as triggerPluginError, f as triggerPluginMount, g as triggerPluginUnmount } from './plugin-DVgSnTfK.cjs';
-export { L as LazyModule, M as Migration, a as MigrationStorageError, P as PackageExportTarget, S as SemVer, V as VERSION, b as bundlerMetadata, c as checkCompatibility, d as compareSemVer, e as createBootSequence, f as createBundle, g as createMigrationRunner, h as createModuleRegistry, i as createSSRCache, j as createTestHarness, k as deferNonCritical, l as env, m as healthCheck, n as lazyModule, p as packageInfo, o as parseSemVer, q as preloadCritical, r as prerenderRoutes, s as satisfies } from './startup-BLfSeL15.cjs';
 
 type Translations = Record<string, string>;
 /**
@@ -213,6 +213,16 @@ interface RouteBase {
     readonly path: string;
     readonly name?: string;
     readonly meta?: RouteMeta;
+    /**
+     * The document head while this route is committed: `title`, `description`,
+     * `canonical`, Open Graph (`og`) and extra `meta` entries. Values may be
+     * getters `(route) => string`, evaluated reactively. Nested records merge,
+     * the deepest winning; `createRouter({ head })` provides the defaults.
+     *
+     * The router manages the head only once some route (or the router) declares
+     * one, so an app without `head` is never touched.
+     */
+    readonly head?: RouteHead;
     readonly children?: RouteDef[];
     readonly beforeEnter?: Guard | Guard[];
     readonly alias?: string | string[];
@@ -306,6 +316,12 @@ interface RouterOptions {
      * - number — cache all routes with this max cache size
      */
     readonly keepAlive?: boolean | string[] | number;
+    /**
+     * Head defaults for every route, plus `titleTemplate`. Declaring it (or a
+     * `head` on any route) makes the router own `document.title` and the
+     * description / canonical / Open Graph tags; see {@link RouteBase.head}.
+     */
+    readonly head?: RouterHeadOptions;
 }
 type ScrollBehavior = (to: RouteContext, from: RouteContext, savedPosition: ScrollPosition | null) => ScrollPosition | null;
 interface ScrollPosition {
@@ -398,8 +414,16 @@ declare class SibuRouter {
     private cleanup;
     private destroyed;
     private navEpoch;
+    private headController;
+    private readonly readyPromise;
+    private resolveReady;
+    private loadedPromise;
     constructor(routes: RouteDef[], options?: RouterOptions);
     private initialize;
+    /** Load the component of every record the current route matched, without instantiating any. */
+    private preloadMatched;
+    /** Settles after the initial navigation and its component loads; see `routerReady()`. */
+    whenReady(): Promise<void>;
     private createInitialRoute;
     private handleLocationChange;
     private getCurrentPath;
@@ -412,6 +436,7 @@ declare class SibuRouter {
     }): Promise<NavigationResult>;
     private static readonly MAX_REDIRECT_DEPTH;
     private performNavigation;
+    private updateHead;
     private resolvePath;
     private isSameRoute;
     private updateHistory;
@@ -574,6 +599,26 @@ declare function router(): {
     beforeResolve: (guard: NavigationGuard) => (() => void) | undefined;
     afterEach: (hook: (to: RouteContext, from: RouteContext) => void) => (() => void) | undefined;
 };
+/**
+ * Resolves once the router has resolved the page's initial location AND loaded
+ * the components that location matched (lazy route chunks included).
+ *
+ * Await it before `hydrate()` on a pre-rendered page: the client tree is then
+ * built with every route component already loaded, so the outlet renders in
+ * the same task and the swap from pre-rendered markup shows no empty frame.
+ * Also resolves if the initial navigation fails or the router is destroyed.
+ *
+ * @returns A promise that never rejects.
+ * @throws If no router has been created yet.
+ *
+ * @example
+ * ```ts
+ * createRouter(routes, { mode: "history" });
+ * await routerReady();
+ * hydrate(App, document.getElementById("app")!);
+ * ```
+ */
+declare function routerReady(): Promise<void>;
 /**
  * Navigate to a target, running every registered guard.
  *
@@ -864,6 +909,90 @@ declare function createMemoryRouter(routes: RouteDef[], _initialPath?: string):
     push: (path: string) => Promise<NavigationResult>;
 };
 
+/**
+ * One head value: a string, nothing, or a getter evaluated reactively against
+ * the committed route — so route params (`(r) => \`Order ${r.params.id}\``) and
+ * translated strings (`() => t("pricing.title")`) both work and stay current.
+ * `null` explicitly clears a value a parent route or the defaults set.
+ */
+type RouteHeadValue = string | null | undefined | ((route: RouteContext) => string | null | undefined);
+/** Open Graph tags a route can set. */
+interface RouteHeadOpenGraph {
+    /** `og:title`. Defaults to the route's title (without `titleTemplate`). */
+    title?: RouteHeadValue;
+    /** `og:description`. Defaults to the route's description. */
+    description?: RouteHeadValue;
+    /** `og:image` — use an ABSOLUTE URL; link-preview bots do not resolve relative ones. */
+    image?: RouteHeadValue;
+    /** `og:url`. Defaults to the canonical URL. */
+    url?: RouteHeadValue;
+    /** `og:type`, e.g. `"website"` or `"article"`. */
+    type?: RouteHeadValue;
+    /** `og:site_name`. */
+    siteName?: RouteHeadValue;
+}
+/**
+ * The `head` of a route record (and of `createRouter({ head })`, as defaults).
+ *
+ * Nested records merge field by field, the deepest record winning; the router
+ * defaults sit underneath every route.
+ */
+interface RouteHead {
+    /** `document.title`. */
+    title?: RouteHeadValue;
+    /** `<meta name="description">`. */
+    description?: RouteHeadValue;
+    /** `<link rel="canonical">` — use an absolute URL. */
+    canonical?: RouteHeadValue;
+    /** Open Graph tags. */
+    og?: RouteHeadOpenGraph;
+    /**
+     * Any other `<meta>` entries (`{ name: "robots", content: "noindex" }`,
+     * `{ name: "twitter:card", content: "summary_large_image" }`). Identified by
+     * their `name` or `property`; an entry with neither is ignored.
+     */
+    meta?: Record<string, RouteHeadValue>[];
+}
+/** Router-level head options: defaults for every route, plus the title template. */
+interface RouterHeadOptions extends RouteHead {
+    /**
+     * Wraps every route title: `"%s · Studio"` or `(title) => \`${title} · Studio\``.
+     * Not applied to the default title itself.
+     */
+    titleTemplate?: string | ((title: string) => string);
+}
+/** One resolved `<head>` element, keyed by what it describes. */
+interface ResolvedHeadTag {
+    /** Identity used to replace / remove the tag across navigations. */
+    key: string;
+    tag: "meta" | "link";
+    attrs: Record<string, string>;
+}
+/** The head a route resolves to. */
+interface ResolvedRouteHead {
+    title: string | null;
+    tags: ResolvedHeadTag[];
+}
+/**
+ * Resolve the head a committed route renders: the router defaults, then every
+ * matched record from the root down. Getters are invoked here, so calling this
+ * inside an effect subscribes to whatever they read.
+ *
+ * @param route The committed route.
+ * @param defaults `createRouter({ head })`, if any.
+ * @returns The title and the tags, after the shared head policy.
+ */
+declare function resolveRouteHead(route: RouteContext, defaults?: RouterHeadOptions): ResolvedRouteHead;
+/**
+ * Serialize a resolved head to HTML, for SSR or a static page. Each tag carries
+ * the `data-sibu-head` marker so the client router adopts it on start-up
+ * instead of duplicating it.
+ *
+ * @param head The result of {@link resolveRouteHead}.
+ * @returns `<title>` plus one element per tag.
+ */
+declare function routeHeadToHTML(head: ResolvedRouteHead): string;
+
 /**
  * Serializable route state that can be transferred from server to client.
  */
@@ -974,4 +1103,4 @@ declare function createSSRRouter(routes: SSRRouteDef[]): {
     }) => string;
 };
 
-export { type AsyncComponent, type AsyncRoute, type Component, type ComponentRoute, type Guard, type GuardResult, KeepAliveRoute, type LazyComponent, type LazyRoute, type NavigationFailure, type NavigationFailureReason, type NavigationGuard, type NavigationNext, type NavigationQuery, type NavigationResult, type NavigationTarget, Outlet, type Params, type QueryValues, type RedirectRoute, Route, type RouteBase, type RouteContext, type RouteDef, type RouteMeta, type RouteTransitionOptions, RouterLink, type RouterOptions, type RouterPlugin, type SSRRouteDef, type SSRRouteState, type ScrollBehavior, type ScrollPosition, SibuRouter, Suspense, Trans, type TranslationParams, __getNavigationEpoch, __removeRouterPagehideHandler, addRoute, afterEach, back, beforeEach, beforeResolve, buildURL, createMemoryRouter, createRouter, createSSRRouter, deserializeRouteState, destroyRouter, forward, getAvailableLocales, getLocale, getRouteInfo, getRouteTransition, go, hasRoute, hasTranslation, hydrateRouter, lazy, navigate, preloadRoute, push, registerTranslations, removeRoute, renderRouteToDocument, renderRouteToString, replace, resolveServerRoute, route, router, routerPlugin, routerState, serializeRouteState, setLocale, setRouteTransition, setRoutes, t, translated };
+export { type AsyncComponent, type AsyncRoute, type Component, type ComponentRoute, type Guard, type GuardResult, KeepAliveRoute, type LazyComponent, type LazyRoute, type NavigationFailure, type NavigationFailureReason, type NavigationGuard, type NavigationNext, type NavigationQuery, type NavigationResult, type NavigationTarget, Outlet, type Params, type QueryValues, type RedirectRoute, type ResolvedHeadTag, type ResolvedRouteHead, Route, type RouteBase, type RouteContext, type RouteDef, type RouteHead, type RouteHeadOpenGraph, type RouteHeadValue, type RouteMeta, type RouteTransitionOptions, type RouterHeadOptions, RouterLink, type RouterOptions, type RouterPlugin, type SSRRouteDef, type SSRRouteState, type ScrollBehavior, type ScrollPosition, SibuRouter, Suspense, Trans, type TranslationParams, __getNavigationEpoch, __removeRouterPagehideHandler, addRoute, afterEach, back, beforeEach, beforeResolve, buildURL, createMemoryRouter, createRouter, createSSRRouter, deserializeRouteState, destroyRouter, forward, getAvailableLocales, getLocale, getRouteInfo, getRouteTransition, go, hasRoute, hasTranslation, hydrateRouter, lazy, navigate, preloadRoute, push, registerTranslations, removeRoute, renderRouteToDocument, renderRouteToString, replace, resolveRouteHead, resolveServerRoute, route, routeHeadToHTML, router, routerPlugin, routerReady, routerState, serializeRouteState, setLocale, setRouteTransition, setRoutes, t, translated };

package/dist/plugins.d.ts

@@ -1,8 +1,8 @@
+export { L as LazyModule, M as Migration, a as MigrationStorageError, P as PackageExportTarget, S as SemVer, V as VERSION, b as bundlerMetadata, c as checkCompatibility, d as compareSemVer, e as createBootSequence, f as createBundle, g as createMigrationRunner, h as createModuleRegistry, i as createSSRCache, j as createTestHarness, k as deferNonCritical, l as env, m as healthCheck, n as lazyModule, p as packageInfo, o as parseSemVer, q as preloadCritical, r as prerenderRoutes, s as satisfies } from './startup-BLfSeL15.js';
 import { A as Accessor } from './signal-EotCj4hS.js';
+export { P as PluginContext, a as PluginInstallCancelledError, b as PluginRegistry, S as SibuPlugin, c as createPlugin, d as createPluginRegistry, i as inject, e as isPluginInstallCancelledError, p as plugin, r as resetPlugins, s as setDefaultPluginRegistry, t as triggerPluginError, f as triggerPluginMount, g as triggerPluginUnmount } from './plugin-DVgSnTfK.js';
 import { C as Component$1, N as NodeChildren } from './types-CJFViL6Q.js';
 import { T as TrustedHTML } from './ssr-Db0Sgdu3.js';
-export { P as PluginContext, a as PluginInstallCancelledError, b as PluginRegistry, S as SibuPlugin, c as createPlugin, d as createPluginRegistry, i as inject, e as isPluginInstallCancelledError, p as plugin, r as resetPlugins, s as setDefaultPluginRegistry, t as triggerPluginError, f as triggerPluginMount, g as triggerPluginUnmount } from './plugin-DVgSnTfK.js';
-export { L as LazyModule, M as Migration, a as MigrationStorageError, P as PackageExportTarget, S as SemVer, V as VERSION, b as bundlerMetadata, c as checkCompatibility, d as compareSemVer, e as createBootSequence, f as createBundle, g as createMigrationRunner, h as createModuleRegistry, i as createSSRCache, j as createTestHarness, k as deferNonCritical, l as env, m as healthCheck, n as lazyModule, p as packageInfo, o as parseSemVer, q as preloadCritical, r as prerenderRoutes, s as satisfies } from './startup-BLfSeL15.js';
 
 type Translations = Record<string, string>;
 /**
@@ -213,6 +213,16 @@ interface RouteBase {
     readonly path: string;
     readonly name?: string;
     readonly meta?: RouteMeta;
+    /**
+     * The document head while this route is committed: `title`, `description`,
+     * `canonical`, Open Graph (`og`) and extra `meta` entries. Values may be
+     * getters `(route) => string`, evaluated reactively. Nested records merge,
+     * the deepest winning; `createRouter({ head })` provides the defaults.
+     *
+     * The router manages the head only once some route (or the router) declares
+     * one, so an app without `head` is never touched.
+     */
+    readonly head?: RouteHead;
     readonly children?: RouteDef[];
     readonly beforeEnter?: Guard | Guard[];
     readonly alias?: string | string[];
@@ -306,6 +316,12 @@ interface RouterOptions {
      * - number — cache all routes with this max cache size
      */
     readonly keepAlive?: boolean | string[] | number;
+    /**
+     * Head defaults for every route, plus `titleTemplate`. Declaring it (or a
+     * `head` on any route) makes the router own `document.title` and the
+     * description / canonical / Open Graph tags; see {@link RouteBase.head}.
+     */
+    readonly head?: RouterHeadOptions;
 }
 type ScrollBehavior = (to: RouteContext, from: RouteContext, savedPosition: ScrollPosition | null) => ScrollPosition | null;
 interface ScrollPosition {
@@ -398,8 +414,16 @@ declare class SibuRouter {
     private cleanup;
     private destroyed;
     private navEpoch;
+    private headController;
+    private readonly readyPromise;
+    private resolveReady;
+    private loadedPromise;
     constructor(routes: RouteDef[], options?: RouterOptions);
     private initialize;
+    /** Load the component of every record the current route matched, without instantiating any. */
+    private preloadMatched;
+    /** Settles after the initial navigation and its component loads; see `routerReady()`. */
+    whenReady(): Promise<void>;
     private createInitialRoute;
     private handleLocationChange;
     private getCurrentPath;
@@ -412,6 +436,7 @@ declare class SibuRouter {
     }): Promise<NavigationResult>;
     private static readonly MAX_REDIRECT_DEPTH;
     private performNavigation;
+    private updateHead;
     private resolvePath;
     private isSameRoute;
     private updateHistory;
@@ -574,6 +599,26 @@ declare function router(): {
     beforeResolve: (guard: NavigationGuard) => (() => void) | undefined;
     afterEach: (hook: (to: RouteContext, from: RouteContext) => void) => (() => void) | undefined;
 };
+/**
+ * Resolves once the router has resolved the page's initial location AND loaded
+ * the components that location matched (lazy route chunks included).
+ *
+ * Await it before `hydrate()` on a pre-rendered page: the client tree is then
+ * built with every route component already loaded, so the outlet renders in
+ * the same task and the swap from pre-rendered markup shows no empty frame.
+ * Also resolves if the initial navigation fails or the router is destroyed.
+ *
+ * @returns A promise that never rejects.
+ * @throws If no router has been created yet.
+ *
+ * @example
+ * ```ts
+ * createRouter(routes, { mode: "history" });
+ * await routerReady();
+ * hydrate(App, document.getElementById("app")!);
+ * ```
+ */
+declare function routerReady(): Promise<void>;
 /**
  * Navigate to a target, running every registered guard.
  *
@@ -864,6 +909,90 @@ declare function createMemoryRouter(routes: RouteDef[], _initialPath?: string):
     push: (path: string) => Promise<NavigationResult>;
 };
 
+/**
+ * One head value: a string, nothing, or a getter evaluated reactively against
+ * the committed route — so route params (`(r) => \`Order ${r.params.id}\``) and
+ * translated strings (`() => t("pricing.title")`) both work and stay current.
+ * `null` explicitly clears a value a parent route or the defaults set.
+ */
+type RouteHeadValue = string | null | undefined | ((route: RouteContext) => string | null | undefined);
+/** Open Graph tags a route can set. */
+interface RouteHeadOpenGraph {
+    /** `og:title`. Defaults to the route's title (without `titleTemplate`). */
+    title?: RouteHeadValue;
+    /** `og:description`. Defaults to the route's description. */
+    description?: RouteHeadValue;
+    /** `og:image` — use an ABSOLUTE URL; link-preview bots do not resolve relative ones. */
+    image?: RouteHeadValue;
+    /** `og:url`. Defaults to the canonical URL. */
+    url?: RouteHeadValue;
+    /** `og:type`, e.g. `"website"` or `"article"`. */
+    type?: RouteHeadValue;
+    /** `og:site_name`. */
+    siteName?: RouteHeadValue;
+}
+/**
+ * The `head` of a route record (and of `createRouter({ head })`, as defaults).
+ *
+ * Nested records merge field by field, the deepest record winning; the router
+ * defaults sit underneath every route.
+ */
+interface RouteHead {
+    /** `document.title`. */
+    title?: RouteHeadValue;
+    /** `<meta name="description">`. */
+    description?: RouteHeadValue;
+    /** `<link rel="canonical">` — use an absolute URL. */
+    canonical?: RouteHeadValue;
+    /** Open Graph tags. */
+    og?: RouteHeadOpenGraph;
+    /**
+     * Any other `<meta>` entries (`{ name: "robots", content: "noindex" }`,
+     * `{ name: "twitter:card", content: "summary_large_image" }`). Identified by
+     * their `name` or `property`; an entry with neither is ignored.
+     */
+    meta?: Record<string, RouteHeadValue>[];
+}
+/** Router-level head options: defaults for every route, plus the title template. */
+interface RouterHeadOptions extends RouteHead {
+    /**
+     * Wraps every route title: `"%s · Studio"` or `(title) => \`${title} · Studio\``.
+     * Not applied to the default title itself.
+     */
+    titleTemplate?: string | ((title: string) => string);
+}
+/** One resolved `<head>` element, keyed by what it describes. */
+interface ResolvedHeadTag {
+    /** Identity used to replace / remove the tag across navigations. */
+    key: string;
+    tag: "meta" | "link";
+    attrs: Record<string, string>;
+}
+/** The head a route resolves to. */
+interface ResolvedRouteHead {
+    title: string | null;
+    tags: ResolvedHeadTag[];
+}
+/**
+ * Resolve the head a committed route renders: the router defaults, then every
+ * matched record from the root down. Getters are invoked here, so calling this
+ * inside an effect subscribes to whatever they read.
+ *
+ * @param route The committed route.
+ * @param defaults `createRouter({ head })`, if any.
+ * @returns The title and the tags, after the shared head policy.
+ */
+declare function resolveRouteHead(route: RouteContext, defaults?: RouterHeadOptions): ResolvedRouteHead;
+/**
+ * Serialize a resolved head to HTML, for SSR or a static page. Each tag carries
+ * the `data-sibu-head` marker so the client router adopts it on start-up
+ * instead of duplicating it.
+ *
+ * @param head The result of {@link resolveRouteHead}.
+ * @returns `<title>` plus one element per tag.
+ */
+declare function routeHeadToHTML(head: ResolvedRouteHead): string;
+
 /**
  * Serializable route state that can be transferred from server to client.
  */
@@ -974,4 +1103,4 @@ declare function createSSRRouter(routes: SSRRouteDef[]): {
     }) => string;
 };
 
-export { type AsyncComponent, type AsyncRoute, type Component, type ComponentRoute, type Guard, type GuardResult, KeepAliveRoute, type LazyComponent, type LazyRoute, type NavigationFailure, type NavigationFailureReason, type NavigationGuard, type NavigationNext, type NavigationQuery, type NavigationResult, type NavigationTarget, Outlet, type Params, type QueryValues, type RedirectRoute, Route, type RouteBase, type RouteContext, type RouteDef, type RouteMeta, type RouteTransitionOptions, RouterLink, type RouterOptions, type RouterPlugin, type SSRRouteDef, type SSRRouteState, type ScrollBehavior, type ScrollPosition, SibuRouter, Suspense, Trans, type TranslationParams, __getNavigationEpoch, __removeRouterPagehideHandler, addRoute, afterEach, back, beforeEach, beforeResolve, buildURL, createMemoryRouter, createRouter, createSSRRouter, deserializeRouteState, destroyRouter, forward, getAvailableLocales, getLocale, getRouteInfo, getRouteTransition, go, hasRoute, hasTranslation, hydrateRouter, lazy, navigate, preloadRoute, push, registerTranslations, removeRoute, renderRouteToDocument, renderRouteToString, replace, resolveServerRoute, route, router, routerPlugin, routerState, serializeRouteState, setLocale, setRouteTransition, setRoutes, t, translated };
+export { type AsyncComponent, type AsyncRoute, type Component, type ComponentRoute, type Guard, type GuardResult, KeepAliveRoute, type LazyComponent, type LazyRoute, type NavigationFailure, type NavigationFailureReason, type NavigationGuard, type NavigationNext, type NavigationQuery, type NavigationResult, type NavigationTarget, Outlet, type Params, type QueryValues, type RedirectRoute, type ResolvedHeadTag, type ResolvedRouteHead, Route, type RouteBase, type RouteContext, type RouteDef, type RouteHead, type RouteHeadOpenGraph, type RouteHeadValue, type RouteMeta, type RouteTransitionOptions, type RouterHeadOptions, RouterLink, type RouterOptions, type RouterPlugin, type SSRRouteDef, type SSRRouteState, type ScrollBehavior, type ScrollPosition, SibuRouter, Suspense, Trans, type TranslationParams, __getNavigationEpoch, __removeRouterPagehideHandler, addRoute, afterEach, back, beforeEach, beforeResolve, buildURL, createMemoryRouter, createRouter, createSSRRouter, deserializeRouteState, destroyRouter, forward, getAvailableLocales, getLocale, getRouteInfo, getRouteTransition, go, hasRoute, hasTranslation, hydrateRouter, lazy, navigate, preloadRoute, push, registerTranslations, removeRoute, renderRouteToDocument, renderRouteToString, replace, resolveRouteHead, resolveServerRoute, route, routeHeadToHTML, router, routerPlugin, routerReady, routerState, serializeRouteState, setLocale, setRouteTransition, setRoutes, t, translated };