sibujs 1.0.0-beta.1

package/dist/plugins.d.cts

@@ -0,0 +1,393 @@
+type Translations = Record<string, string>;
+type Params$1 = Record<string, string | number>;
+declare function setLocale(locale: string): void;
+/**
+ * Get the current locale reactively.
+ */
+declare function getLocale(): string;
+declare function registerTranslations(locale: string, messages: Translations): void;
+declare function t(key: string, params?: Params$1): string;
+/**
+ * Trans component — renders a translated string reactively.
+ * Automatically updates when the locale changes.
+ *
+ * @param key Translation key
+ * @param params Optional interpolation parameters
+ * @returns An HTMLElement (span) that reactively shows the translated text
+ *
+ * @example
+ * ```ts
+ * registerTranslations("en", { greeting: "Hello, {name}!" });
+ * registerTranslations("es", { greeting: "Hola, {name}!" });
+ *
+ * div({ nodes: [Trans("greeting", { name: "World" })] });
+ * // When locale changes, the text updates automatically
+ * ```
+ */
+declare function Trans(key: string, params?: Params$1): HTMLElement;
+/**
+ * Check if a translation key exists for the current locale.
+ */
+declare function hasTranslation(key: string): boolean;
+/**
+ * Get all available locales.
+ */
+declare function getAvailableLocales(): string[];
+
+type Component = () => Element;
+type AsyncComponent = () => Promise<Element>;
+type LazyComponent = () => Promise<{
+    default: Component;
+}>;
+type Params = Record<string, string>;
+interface RouteContext {
+    readonly path: string;
+    readonly params: Params;
+    readonly query: Params;
+    readonly hash: string;
+    readonly meta: RouteMeta;
+    readonly matched: RouteDef[];
+}
+type GuardResult = boolean | string | Promise<boolean | string>;
+type Guard = (to: RouteContext, from?: RouteContext) => GuardResult;
+type NavigationGuard = (to: RouteContext, from: RouteContext, next: NavigationNext) => void;
+type NavigationNext = (result?: boolean | string | Error) => void;
+type RouteMeta = Record<string, unknown>;
+interface RouteBase {
+    readonly path: string;
+    readonly name?: string;
+    readonly meta?: RouteMeta;
+    readonly children?: RouteDef[];
+    readonly beforeEnter?: Guard | Guard[];
+    readonly alias?: string | string[];
+}
+interface ComponentRoute extends RouteBase {
+    readonly component: Component;
+}
+interface AsyncRoute extends RouteBase {
+    readonly component: AsyncComponent | LazyComponent;
+}
+interface RedirectRoute extends RouteBase {
+    readonly redirect: string | ((to: RouteContext) => string);
+}
+type RouteDef = ComponentRoute | AsyncRoute | RedirectRoute;
+interface RouterOptions {
+    readonly mode?: "history" | "hash";
+    readonly base?: string;
+    readonly linkActiveClass?: string;
+    readonly linkExactActiveClass?: string;
+    readonly fallback?: boolean;
+    readonly scrollBehavior?: ScrollBehavior;
+    readonly guardTimeout?: number;
+    readonly cacheSize?: number;
+    readonly errorRetryDelay?: number;
+    readonly preloadStrategy?: "none" | "hover" | "visible";
+}
+type ScrollBehavior = (to: RouteContext, from: RouteContext, savedPosition: ScrollPosition | null) => ScrollPosition | null;
+interface ScrollPosition {
+    readonly x: number;
+    readonly y: number;
+}
+interface NavigationFailure {
+    readonly type: "aborted" | "cancelled" | "duplicated" | "timeout";
+    readonly from: RouteContext;
+    readonly to: RouteContext;
+    readonly error?: Error;
+}
+type NavigationResult = {
+    success: true;
+    route: RouteContext;
+} | {
+    success: false;
+    type: NavigationFailure["type"];
+    failure: NavigationFailure;
+};
+type NavigationTarget = string | {
+    path?: string;
+    name?: string;
+    params?: Params;
+    query?: Params;
+    hash?: string;
+};
+declare class SibuRouter {
+    private options;
+    private matcher;
+    private guards;
+    private loader;
+    private navigator;
+    private currentRouteGetter;
+    private currentRouteSetter;
+    private isReadyGetter;
+    private isReadySetter;
+    private cleanup;
+    constructor(routes: RouteDef[], options?: RouterOptions);
+    private initialize;
+    private createInitialRoute;
+    private handleLocationChange;
+    private getCurrentPath;
+    private createRouteContext;
+    navigate(to: NavigationTarget, options?: {
+        replace?: boolean;
+        state?: unknown;
+    }): Promise<NavigationResult>;
+    private performNavigation;
+    private resolvePath;
+    private isSameRoute;
+    private updateHistory;
+    private handleScrollBehavior;
+    loadComponent(route: RouteDef, routePath: string): Promise<Component>;
+    beforeEach(guard: NavigationGuard): () => void;
+    beforeResolve(guard: NavigationGuard): () => void;
+    afterEach(hook: (to: RouteContext, from: RouteContext) => void): () => void;
+    push(to: NavigationTarget): Promise<NavigationResult>;
+    replace(to: NavigationTarget): Promise<NavigationResult>;
+    go(delta: number): void;
+    back(): void;
+    forward(): void;
+    get currentRoute(): RouteContext;
+    get isReady(): boolean;
+    get isNavigating(): boolean;
+    destroy(): void;
+    clearCache(): void;
+    clearErrorCache(): void;
+    updateRoutes(routes: RouteDef[]): void;
+    /**
+     * Add a route dynamically at runtime.
+     */
+    addRoute(route: RouteDef, parentPath?: string): void;
+    /**
+     * Remove a route by path.
+     */
+    removeRoute(path: string): void;
+    /**
+     * Get the reactive route getter for tracking.
+     */
+    get routeGetter(): () => RouteContext;
+}
+declare function createRouter(routesOrOptions: RouteDef[] | RouterOptions, options?: RouterOptions): SibuRouter;
+/**
+ * Set routes on the global router (replaces existing routes).
+ */
+declare function setRoutes(routes: RouteDef[]): void;
+declare function route(): RouteContext;
+declare function router(): {
+    currentRoute: RouteContext;
+    isReady: boolean;
+    isNavigating: boolean;
+    push: (to: NavigationTarget) => Promise<NavigationResult> | undefined;
+    replace: (to: NavigationTarget) => Promise<NavigationResult> | undefined;
+    go: (delta: number) => void | undefined;
+    back: () => void | undefined;
+    forward: () => void | undefined;
+    beforeEach: (guard: NavigationGuard) => (() => void) | undefined;
+    beforeResolve: (guard: NavigationGuard) => (() => void) | undefined;
+    afterEach: (hook: (to: RouteContext, from: RouteContext) => void) => (() => void) | undefined;
+};
+declare function navigate(to: NavigationTarget, options?: {
+    replace?: boolean;
+    state?: unknown;
+}): Promise<NavigationResult>;
+declare function push(to: NavigationTarget): Promise<NavigationResult>;
+declare function replace(to: NavigationTarget): Promise<NavigationResult>;
+declare function go(delta: number): void;
+declare function back(): void;
+declare function forward(): void;
+declare function beforeEach(guard: NavigationGuard): () => void;
+declare function beforeResolve(guard: NavigationGuard): () => void;
+declare function afterEach(hook: (to: RouteContext, from: RouteContext) => void): () => void;
+declare function Route(): Node;
+declare function RouterLink(props: {
+    to: NavigationTarget;
+    replace?: boolean;
+    activeClass?: string;
+    exactActiveClass?: string;
+    nodes?: string | Node | (string | Node)[];
+    target?: string;
+    rel?: string;
+    [key: string]: unknown;
+}): HTMLElement;
+declare function Suspense(props: {
+    fallback?: () => HTMLElement | HTMLElement;
+    nodes: () => HTMLElement | Promise<HTMLElement>;
+}): Node;
+/**
+ * Creates a lazy-loaded component
+ */
+declare function lazy(importFn: () => Promise<{
+    default: Component;
+}>): LazyComponent;
+/**
+ * Preloads a route component
+ */
+declare function preloadRoute(to: NavigationTarget): Promise<void>;
+/**
+ * Validates if a route exists
+ */
+declare function hasRoute(name: string): boolean;
+/**
+ * Gets route information by name
+ */
+declare function getRouteInfo(name: string): RouteDef | null;
+/**
+ * Builds a URL for a route
+ */
+declare function buildURL(to: NavigationTarget): string;
+declare function destroyRouter(): void;
+/**
+ * Outlet renders the child route component within a layout.
+ * Use inside a parent route's component to render matched children.
+ */
+declare function Outlet(): Node;
+/**
+ * Add a route at runtime.
+ */
+declare function addRoute(route: RouteDef, parentPath?: string): void;
+/**
+ * Remove a route at runtime.
+ */
+declare function removeRoute(path: string): void;
+/**
+ * routerState provides centralized reactive access to router state.
+ */
+declare function routerState(): {
+    currentPath: () => string;
+    params: () => Params;
+    query: () => Params;
+    hash: () => string;
+    meta: () => RouteMeta;
+    isNavigating: boolean;
+    isReady: boolean;
+};
+interface RouterPlugin {
+    name: string;
+    onNavigate?: (to: RouteContext, from: RouteContext) => void;
+    onError?: (error: Error, to: RouteContext) => void;
+    onReady?: () => void;
+}
+/**
+ * Register a router plugin (analytics, breadcrumbs, permissions, etc.).
+ */
+declare function routerPlugin(plugin: RouterPlugin): () => void;
+interface RouteTransitionOptions {
+    enterClass?: string;
+    leaveClass?: string;
+    duration?: number;
+}
+/**
+ * Configure route transition animations.
+ */
+declare function setRouteTransition(options: RouteTransitionOptions): void;
+/**
+ * Get current route transition options.
+ */
+declare function getRouteTransition(): RouteTransitionOptions | null;
+/**
+ * createMemoryRouter creates a router that doesn't interact with browser history.
+ * Useful for testing and SSR.
+ */
+declare function createMemoryRouter(routes: RouteDef[], _initialPath?: string): {
+    router: SibuRouter;
+    currentPath: () => string;
+    push: (path: string) => Promise<NavigationResult>;
+};
+
+/**
+ * Serializable route state that can be transferred from server to client.
+ */
+interface SSRRouteState {
+    path: string;
+    params: Record<string, string>;
+    query: Record<string, string>;
+    hash: string;
+    meta: Record<string, unknown>;
+    name?: string;
+}
+/**
+ * Simple route definition for SSR (subset of full RouteDef).
+ */
+interface SSRRouteDef {
+    path: string;
+    name?: string;
+    meta?: Record<string, unknown>;
+    component: () => HTMLElement;
+    redirect?: string;
+    children?: SSRRouteDef[];
+}
+/**
+ * Resolve a route on the server without any browser APIs.
+ * Performs route matching, param extraction, query parsing.
+ * Does NOT use window, history, or any browser globals.
+ */
+declare function resolveServerRoute(url: string, routes: SSRRouteDef[]): {
+    route: SSRRouteState;
+    component: (() => HTMLElement) | null;
+    redirect?: string;
+};
+/**
+ * Render a route's component to HTML string on the server.
+ * Combines route resolution with renderToString.
+ */
+declare function renderRouteToString(url: string, routes: SSRRouteDef[], _options?: {
+    title?: string;
+    scripts?: string[];
+    links?: Record<string, string>[];
+}): {
+    html: string;
+    state: SSRRouteState;
+};
+/**
+ * Generate the full HTML document for a route including serialized state.
+ * Uses renderToDocument pattern with embedded route state.
+ */
+declare function renderRouteToDocument(url: string, routes: SSRRouteDef[], options?: {
+    title?: string;
+    meta?: Record<string, string>[];
+    links?: Record<string, string>[];
+    scripts?: string[];
+    headExtra?: string;
+}): string;
+/**
+ * Serialize route state for embedding in HTML.
+ * Uses a specific key (__SIBU_ROUTE_STATE__) distinct from the generic SSR data key.
+ */
+declare function serializeRouteState(state: SSRRouteState): string;
+/**
+ * Deserialize route state on the client from server-embedded data.
+ * Reads from window.__SIBU_ROUTE_STATE__.
+ */
+declare function deserializeRouteState(): SSRRouteState | undefined;
+/**
+ * Initialize the client-side router from server-rendered state.
+ * Hydrates the existing HTML and picks up where server left off.
+ * Skips initial route resolution and guard execution since the server
+ * already resolved and rendered the correct route.
+ */
+declare function hydrateRouter(routes: SSRRouteDef[], options?: {
+    container?: HTMLElement;
+}): void;
+/**
+ * Create a server-safe router instance that works without browser APIs.
+ * For use in Node.js SSR rendering. Returns an object with resolve,
+ * renderToString, and renderToDocument methods -- none of which require
+ * window, history, or document.
+ */
+declare function createSSRRouter(routes: SSRRouteDef[]): {
+    resolve: (url: string) => {
+        route: SSRRouteState;
+        component: (() => HTMLElement) | null;
+        redirect?: string;
+    };
+    renderToString: (url: string) => {
+        html: string;
+        state: SSRRouteState;
+    };
+    renderToDocument: (url: string, options?: {
+        title?: string;
+        meta?: Record<string, string>[];
+        links?: Record<string, string>[];
+        scripts?: string[];
+        headExtra?: string;
+    }) => string;
+};
+
+export { type AsyncComponent, type AsyncRoute, type Component, type ComponentRoute, type Guard, type GuardResult, type LazyComponent, type NavigationFailure, type NavigationGuard, type NavigationNext, type NavigationResult, type NavigationTarget, Outlet, type Params, 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, 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 };