@ilha/router 0.1.1 → 0.2.1

package/dist/index.d.ts

@@ -4,6 +4,8 @@ import { HydratableOptions, Island } from "ilha";
 interface RouteRecord {
   pattern: string;
   island: Island<any, any>;
+  /** Merged loader chain (layouts outer→inner, then page) — `undefined` if no loaders. */
+  loader?: Loader<any>;
 }
 interface RouteSnapshot {
   path: string;
@@ -18,8 +20,55 @@ interface AppError {
 }
 type LayoutHandler = (children: Island<any, any>) => Island<any, any>;
 type ErrorHandler = (error: AppError, route: RouteSnapshot) => Island<any, any>;
+interface LoaderContext {
+  params: Record<string, string>;
+  request: Request;
+  url: URL;
+  signal: AbortSignal;
+}
+type Loader<T> = (ctx: LoaderContext) => Promise<T> | T;
+/**
+ * Identity function for declaring a loader. Exists purely as a type anchor and
+ * a marker for the Vite plugin to detect by export name.
+ */
+declare function loader<T>(fn: Loader<T>): Loader<T>;
+/** Extract the return type of a loader. */
+type InferLoader<L> = L extends Loader<infer T> ? Awaited<T> : never;
+/**
+ * Merge multiple loader return types into a single object type.
+ * Later loaders override earlier ones on key collision — matching runtime merge.
+ *
+ * @example
+ * type PageInput = MergeLoaders<[typeof rootLayoutLoad, typeof sectionLayoutLoad, typeof pageLoad]>;
+ */
+type MergeLoaders<Ls extends readonly Loader<any>[]> = Ls extends readonly [infer First extends Loader<any>, ...infer Rest extends readonly Loader<any>[]] ? Rest extends readonly [] ? InferLoader<First> : Omit<InferLoader<First>, keyof MergeLoaders<Rest>> & MergeLoaders<Rest> : {};
+declare class Redirect {
+  readonly __ilhaRedirect: true;
+  readonly to: string;
+  readonly status: number;
+  constructor(to: string, status?: number);
+}
+declare class LoaderError {
+  readonly __ilhaLoaderError: true;
+  readonly status: number;
+  readonly message: string;
+  constructor(status: number, message: string);
+}
+declare function redirect(to: string, status?: number): never;
+declare function error(status: number, message: string): never;
+/**
+ * Compose a list of loaders into a single loader. Later loaders win on key
+ * collision (page loader overrides layout loader for the same key). All loaders
+ * run concurrently within a chain since they share the same abort signal and
+ * request — re-fetching is cheap with a request-scoped cache (future work).
+ *
+ * For v1 we run them in parallel via `Promise.all`. If a loader throws a
+ * `Redirect` or `LoaderError`, the composed loader re-throws it unchanged.
+ */
+declare function composeLoaders<Ls extends readonly Loader<any>[]>(loaders: Ls): Loader<MergeLoaders<Ls>>;
 declare function wrapLayout(layout: LayoutHandler, page: Island<any, any>): Island<any, any>;
 declare function wrapError(handler: ErrorHandler, page: Island<any, any>): Island<any, any>;
+declare function defineLayout(layout: LayoutHandler): LayoutHandler;
 interface NavigateOptions {
   replace?: boolean;
 }
@@ -32,12 +81,65 @@ interface MountOptions {
   hydrate?: boolean;
   registry?: Record<string, Island<any, any>>;
 }
+/** Response envelope returned by `renderResponse` — lets the host app handle redirects. */
+type RenderResponse = {
+  kind: "html";
+  html: string;
+  status?: number;
+} | {
+  kind: "redirect";
+  to: string;
+  status: number;
+} | {
+  kind: "error";
+  status: number;
+  message: string;
+  html: string;
+};
 interface RouterBuilder {
-  route(pattern: string, island: Island<any, any>): RouterBuilder;
+  /**
+   * Register a route. The optional `loader` is the merged loader chain
+   * (layout loaders outer→inner followed by the page loader) produced by
+   * the FS-routing codegen.
+   */
+  route(pattern: string, island: Island<any, any>, loader?: Loader<any>): RouterBuilder;
+  /**
+   * Attach (or replace) a loader on an already-registered route pattern.
+   * Used by the `ilha:loaders` virtual module to wire server-only loaders
+   * onto the client-safe `pageRouter` at SSR time. No-op if the pattern
+   * was never registered via `.route()`.
+   */
+  attachLoader(pattern: string, loader: Loader<any>): RouterBuilder;
   prime(): void;
   mount(target: string | Element, options?: MountOptions): () => void;
   render(url: string | URL): string;
-  renderHydratable(url: string | URL, registry: Record<string, Island<any, any>>, options?: HydratableRenderOptions): Promise<string>;
+  renderHydratable(url: string | URL, registry: Record<string, Island<any, any>>, options?: HydratableRenderOptions, request?: Request): Promise<string>;
+  /**
+   * Like `renderHydratable` but surfaces loader redirects and errors as
+   * structured responses instead of baking them into HTML. Prefer this from
+   * host server code so you can emit proper 302 / 4xx responses.
+   */
+  renderResponse(url: string | URL, registry: Record<string, Island<any, any>>, options?: HydratableRenderOptions, request?: Request): Promise<RenderResponse>;
+  /**
+   * Run the loader chain for a given URL without rendering. Used by the
+   * `/__ilha/loader` endpoint the Vite plugin exposes for client-side
+   * navigation. Returns the raw loader result, a redirect sentinel, or an
+   * error sentinel.
+   */
+  runLoader(url: string | URL, request?: Request): Promise<{
+    kind: "data";
+    data: Record<string, unknown>;
+  } | {
+    kind: "redirect";
+    to: string;
+    status: number;
+  } | {
+    kind: "error";
+    status: number;
+    message: string;
+  } | {
+    kind: "not-found";
+  }>;
   /**
    * Hydrate the application - combines prime(), mount(), and router.mount() into one call.
    * @param registry - The island registry from ilha:registry
@@ -46,6 +148,14 @@ interface RouterBuilder {
    */
   hydrate(registry: Record<string, Island<any, any>>, options?: HydrateOptions): () => void;
 }
+/** Path of the loader endpoint served by the Vite plugin / production adapter. */
+declare const LOADER_ENDPOINT = "/__ilha/loader";
+/**
+ * Prefetch loader data for a given path. Safe to call repeatedly — a single
+ * inflight request is reused until it either resolves (and is consumed by
+ * navigation) or is superseded by another prefetch.
+ */
+declare function prefetch(pathWithSearch: string): void;
 declare const routePath: {
   (): string;
   (value: string): void;
@@ -84,23 +194,19 @@ declare function useRoute(): {
  * Prime route context signals from the current `location` so that islands
  * hydrated by `ilha.mount()` see the correct route values on their first
  * render — preventing a mismatch morph that would destroy hydrated bindings.
- *
- * Call this **before** `ilha.mount()` and **after** all routes have been
- * registered (i.e. after the `router().route(…).route(…)` chain).
- *
- * ```ts
- * import { mount } from "ilha";
- * import { pageRouter } from "ilha:pages";
- * import { registry } from "ilha:registry";
- *
- * pageRouter.prime();              // ← sync signals first
- * mount(registry, { root: … });   // ← then hydrate islands
- * pageRouter.mount("#app", { hydrate: true });
- * ```
  */
 declare function prime(): void;
 declare function navigate(to: string, opts?: NavigateOptions): void;
-declare function enableLinkInterception(root?: Element | Document): () => void;
+interface LinkInterceptionOptions {
+  /**
+   * Prefetch loader data on `mouseenter` for eligible links. Links opt in via
+   * the `data-prefetch` attribute (set `data-prefetch="false"` to opt out a
+   * specific link even when the framework is configured to prefetch by default).
+   * Default: `true` — prefetches on hover for any link with `data-prefetch`.
+   */
+  prefetch?: boolean;
+}
+declare function enableLinkInterception(root?: Element | Document, options?: LinkInterceptionOptions): () => void;
 declare const RouterView: Island<Record<string, unknown>, Record<string, never>>;
 declare const RouterLink: Island<Record<string, unknown>, {
   [x: string]: never;
@@ -115,11 +221,16 @@ declare const _default: {
   isActive: typeof isActive;
   enableLinkInterception: typeof enableLinkInterception;
   prime: typeof prime;
+  prefetch: typeof prefetch;
   RouterView: Island<Record<string, unknown>, Record<string, never>>;
   RouterLink: Island<Record<string, unknown>, {
     [x: string]: never;
     href: string;
   } & Record<"label", string>>;
+  loader: typeof loader;
+  redirect: typeof redirect;
+  error: typeof error;
+  composeLoaders: typeof composeLoaders;
 };
 //#endregion
-export { AppError, ErrorHandler, HydratableRenderOptions, HydrateOptions, LayoutHandler, MountOptions, NavigateOptions, RouteRecord, RouteSnapshot, RouterBuilder, RouterLink, RouterView, _default as default, enableLinkInterception, isActive, navigate, prime, routeHash, routeParams, routePath, routeSearch, router, useRoute, wrapError, wrapLayout };
+export { AppError, ErrorHandler, HydratableRenderOptions, HydrateOptions, InferLoader, LOADER_ENDPOINT, LayoutHandler, LinkInterceptionOptions, Loader, LoaderContext, LoaderError, MergeLoaders, MountOptions, NavigateOptions, Redirect, RenderResponse, RouteRecord, RouteSnapshot, RouterBuilder, RouterLink, RouterView, composeLoaders, _default as default, defineLayout, enableLinkInterception, error, isActive, loader, navigate, prefetch, prime, redirect, routeHash, routeParams, routePath, routeSearch, router, useRoute, wrapError, wrapLayout };