@matthesketh/utopia-router 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,215 @@
+import * as _matthesketh_utopia_core from '@matthesketh/utopia-core';
+
+/**
+ * A compiled route entry in the route table.
+ *
+ * Routes are built at compile time from the file system manifest and stored
+ * as an array. At runtime, incoming URLs are matched against `pattern`.
+ */
+interface Route {
+    /** URL pattern like '/users/:id' or '/blog/:slug'. */
+    path: string;
+    /** Compiled regex for matching incoming URLs against this route. */
+    pattern: RegExp;
+    /** Parameter names extracted from the path (e.g., ['id'] for '/users/:id'). */
+    params: string[];
+    /** Lazy component import — called only when the route is matched. */
+    component: () => Promise<any>;
+    /** Optional layout component that wraps the page. */
+    layout?: () => Promise<any>;
+    /** Optional error boundary component shown when loading fails. */
+    error?: () => Promise<any>;
+}
+/**
+ * The result of successfully matching a URL against a route.
+ */
+interface RouteMatch {
+    /** The matched route entry. */
+    route: Route;
+    /** Extracted parameter values keyed by parameter name. */
+    params: Record<string, string>;
+    /** The full URL that was matched. */
+    url: URL;
+}
+/**
+ * Observable router state exposed as signals.
+ */
+interface RouterState {
+    /** The currently matched route, or null if no route matches. */
+    current: RouteMatch | null;
+    /** Whether a navigation is currently in progress. */
+    navigating: boolean;
+}
+/**
+ * Callback signature for beforeNavigate hooks (navigation guards).
+ *
+ * Return `false` to cancel the navigation, or `void`/`true` to allow it.
+ * Returning a string redirects to that URL instead.
+ */
+type BeforeNavigateHook = (from: RouteMatch | null, to: RouteMatch | null) => boolean | string | void | Promise<boolean | string | void>;
+
+/**
+ * Converts a file-system path (relative to the routes directory) into a URL
+ * route pattern.
+ *
+ * @param filePath - File path like 'src/routes/blog/[slug]/+page.utopia'
+ * @returns URL pattern like '/blog/:slug'
+ *
+ * @example
+ * filePathToRoute('src/routes/+page.utopia')             // '/'
+ * filePathToRoute('src/routes/about/+page.utopia')       // '/about'
+ * filePathToRoute('src/routes/blog/[slug]/+page.utopia') // '/blog/:slug'
+ * filePathToRoute('src/routes/[...rest]/+page.utopia')   // '/*rest'
+ * filePathToRoute('src/routes/(auth)/login/+page.utopia') // '/login'
+ */
+declare function filePathToRoute(filePath: string): string;
+/**
+ * Compiles a URL route pattern into a regex and extracts parameter names.
+ *
+ * @param pattern - Route pattern like '/blog/:slug' or '/*rest'
+ * @returns Object with `regex` and `params` array
+ *
+ * @example
+ * compilePattern('/blog/:slug')
+ * // { regex: /^\/blog\/([^/]+)\/?$/, params: ['slug'] }
+ *
+ * compilePattern('/*rest')
+ * // { regex: /^\/(.+)\/?$/, params: ['rest'] }
+ */
+declare function compilePattern(pattern: string): {
+    regex: RegExp;
+    params: string[];
+};
+/**
+ * Matches a URL against an ordered list of routes. Returns the first match
+ * with extracted parameters, or null if no route matches.
+ *
+ * Routes are tested in order, so more specific routes should come first.
+ * The `buildRouteTable` function handles this ordering automatically.
+ *
+ * @param url - The URL to match
+ * @param routes - Ordered array of compiled routes
+ * @returns The matched route with params, or null
+ */
+declare function matchRoute(url: URL, routes: Route[]): RouteMatch | null;
+/**
+ * Builds an ordered route table from a Vite-style glob import manifest.
+ *
+ * The manifest maps file paths to lazy import functions, e.g.:
+ * ```ts
+ * {
+ *   'src/routes/+page.utopia': () => import('./routes/+page.utopia'),
+ *   'src/routes/about/+page.utopia': () => import('./routes/about/+page.utopia'),
+ *   'src/routes/blog/[slug]/+page.utopia': () => import('./routes/blog/[slug]/+page.utopia'),
+ *   'src/routes/+layout.utopia': () => import('./routes/+layout.utopia'),
+ *   'src/routes/+error.utopia': () => import('./routes/+error.utopia'),
+ * }
+ * ```
+ *
+ * Routes are sorted so that:
+ * 1. Static routes come before dynamic routes
+ * 2. Dynamic parameter routes come before catch-all routes
+ * 3. More specific routes (more static segments) come first
+ *
+ * @param manifest - Record of file paths to lazy import functions
+ * @returns Ordered array of compiled Route objects
+ */
+declare function buildRouteTable(manifest: Record<string, () => Promise<any>>): Route[];
+
+/** The currently matched route, or null if no route matches. */
+declare const currentRoute: _matthesketh_utopia_core.Signal<RouteMatch | null>;
+/** Whether a navigation is currently in progress (loading component, etc.). */
+declare const isNavigating: _matthesketh_utopia_core.Signal<boolean>;
+/**
+ * Initialize the router with a compiled route table.
+ *
+ * This must be called once at application startup. It:
+ * 1. Stores the route table
+ * 2. Matches the current URL and sets `currentRoute`
+ * 3. Sets up popstate listener for browser back/forward
+ * 4. Sets up click listener for <a> interception
+ *
+ * @param routeTable - Array of compiled routes from `buildRouteTable()`
+ */
+declare function createRouter(routeTable: Route[]): void;
+/**
+ * Navigate to a new URL.
+ *
+ * @param url - The URL to navigate to (absolute path like '/about' or full URL)
+ * @param options - Navigation options
+ * @param options.replace - If true, replace the current history entry instead of pushing
+ * @returns Promise that resolves when navigation is complete
+ */
+declare function navigate(url: string, options?: {
+    replace?: boolean;
+}): Promise<void>;
+/** Navigate back one entry in the browser history. */
+declare function back(): void;
+/** Navigate forward one entry in the browser history. */
+declare function forward(): void;
+/**
+ * Register a navigation guard that runs before each navigation.
+ *
+ * The hook receives the current and next route matches. It can:
+ * - Return `void` or `true` to allow navigation
+ * - Return `false` to cancel navigation
+ * - Return a string to redirect to a different URL
+ *
+ * @param hook - The guard callback
+ * @returns A function that removes the hook
+ */
+declare function beforeNavigate(hook: BeforeNavigateHook): () => void;
+/**
+ * Tear down the router, removing all event listeners and clearing state.
+ * Primarily useful for testing and HMR.
+ */
+declare function destroy(): void;
+
+/**
+ * Creates a DOM node that renders the current route's component.
+ *
+ * When the route changes:
+ * 1. The old component is unmounted (removed from DOM)
+ * 2. The new component is lazily loaded
+ * 3. If the route has a layout, the page is wrapped in the layout
+ * 4. If loading fails and an error component exists, it is shown instead
+ *
+ * @returns A container DOM node that manages route component lifecycle
+ *
+ * @example
+ * ```ts
+ * const view = createRouterView();
+ * document.getElementById('app')!.appendChild(view);
+ * ```
+ */
+declare function createRouterView(): Node;
+/**
+ * Creates an anchor element that performs client-side navigation when clicked.
+ *
+ * The link integrates with the router's click interception, but also sets up
+ * the correct `href` and can apply active-state CSS classes.
+ *
+ * @param props - Link properties
+ * @param props.href - The URL to navigate to
+ * @param props.children - Child node(s) to render inside the anchor
+ * @param props.class - Optional CSS class name
+ * @param props.activeClass - Optional CSS class applied when the link's href matches the current route
+ * @returns An HTMLAnchorElement
+ *
+ * @example
+ * ```ts
+ * const link = createLink({
+ *   href: '/about',
+ *   children: document.createTextNode('About'),
+ * });
+ * document.body.appendChild(link);
+ * ```
+ */
+declare function createLink(props: {
+    href: string;
+    children: Node | string;
+    class?: string;
+    activeClass?: string;
+}): HTMLAnchorElement;
+
+export { type BeforeNavigateHook, type Route, type RouteMatch, type RouterState, back, beforeNavigate, buildRouteTable, compilePattern, createLink, createRouter, createRouterView, currentRoute, destroy, filePathToRoute, forward, isNavigating, matchRoute, navigate };

package/dist/index.d.ts

@@ -0,0 +1,215 @@
+import * as _matthesketh_utopia_core from '@matthesketh/utopia-core';
+
+/**
+ * A compiled route entry in the route table.
+ *
+ * Routes are built at compile time from the file system manifest and stored
+ * as an array. At runtime, incoming URLs are matched against `pattern`.
+ */
+interface Route {
+    /** URL pattern like '/users/:id' or '/blog/:slug'. */
+    path: string;
+    /** Compiled regex for matching incoming URLs against this route. */
+    pattern: RegExp;
+    /** Parameter names extracted from the path (e.g., ['id'] for '/users/:id'). */
+    params: string[];
+    /** Lazy component import — called only when the route is matched. */
+    component: () => Promise<any>;
+    /** Optional layout component that wraps the page. */
+    layout?: () => Promise<any>;
+    /** Optional error boundary component shown when loading fails. */
+    error?: () => Promise<any>;
+}
+/**
+ * The result of successfully matching a URL against a route.
+ */
+interface RouteMatch {
+    /** The matched route entry. */
+    route: Route;
+    /** Extracted parameter values keyed by parameter name. */
+    params: Record<string, string>;
+    /** The full URL that was matched. */
+    url: URL;
+}
+/**
+ * Observable router state exposed as signals.
+ */
+interface RouterState {
+    /** The currently matched route, or null if no route matches. */
+    current: RouteMatch | null;
+    /** Whether a navigation is currently in progress. */
+    navigating: boolean;
+}
+/**
+ * Callback signature for beforeNavigate hooks (navigation guards).
+ *
+ * Return `false` to cancel the navigation, or `void`/`true` to allow it.
+ * Returning a string redirects to that URL instead.
+ */
+type BeforeNavigateHook = (from: RouteMatch | null, to: RouteMatch | null) => boolean | string | void | Promise<boolean | string | void>;
+
+/**
+ * Converts a file-system path (relative to the routes directory) into a URL
+ * route pattern.
+ *
+ * @param filePath - File path like 'src/routes/blog/[slug]/+page.utopia'
+ * @returns URL pattern like '/blog/:slug'
+ *
+ * @example
+ * filePathToRoute('src/routes/+page.utopia')             // '/'
+ * filePathToRoute('src/routes/about/+page.utopia')       // '/about'
+ * filePathToRoute('src/routes/blog/[slug]/+page.utopia') // '/blog/:slug'
+ * filePathToRoute('src/routes/[...rest]/+page.utopia')   // '/*rest'
+ * filePathToRoute('src/routes/(auth)/login/+page.utopia') // '/login'
+ */
+declare function filePathToRoute(filePath: string): string;
+/**
+ * Compiles a URL route pattern into a regex and extracts parameter names.
+ *
+ * @param pattern - Route pattern like '/blog/:slug' or '/*rest'
+ * @returns Object with `regex` and `params` array
+ *
+ * @example
+ * compilePattern('/blog/:slug')
+ * // { regex: /^\/blog\/([^/]+)\/?$/, params: ['slug'] }
+ *
+ * compilePattern('/*rest')
+ * // { regex: /^\/(.+)\/?$/, params: ['rest'] }
+ */
+declare function compilePattern(pattern: string): {
+    regex: RegExp;
+    params: string[];
+};
+/**
+ * Matches a URL against an ordered list of routes. Returns the first match
+ * with extracted parameters, or null if no route matches.
+ *
+ * Routes are tested in order, so more specific routes should come first.
+ * The `buildRouteTable` function handles this ordering automatically.
+ *
+ * @param url - The URL to match
+ * @param routes - Ordered array of compiled routes
+ * @returns The matched route with params, or null
+ */
+declare function matchRoute(url: URL, routes: Route[]): RouteMatch | null;
+/**
+ * Builds an ordered route table from a Vite-style glob import manifest.
+ *
+ * The manifest maps file paths to lazy import functions, e.g.:
+ * ```ts
+ * {
+ *   'src/routes/+page.utopia': () => import('./routes/+page.utopia'),
+ *   'src/routes/about/+page.utopia': () => import('./routes/about/+page.utopia'),
+ *   'src/routes/blog/[slug]/+page.utopia': () => import('./routes/blog/[slug]/+page.utopia'),
+ *   'src/routes/+layout.utopia': () => import('./routes/+layout.utopia'),
+ *   'src/routes/+error.utopia': () => import('./routes/+error.utopia'),
+ * }
+ * ```
+ *
+ * Routes are sorted so that:
+ * 1. Static routes come before dynamic routes
+ * 2. Dynamic parameter routes come before catch-all routes
+ * 3. More specific routes (more static segments) come first
+ *
+ * @param manifest - Record of file paths to lazy import functions
+ * @returns Ordered array of compiled Route objects
+ */
+declare function buildRouteTable(manifest: Record<string, () => Promise<any>>): Route[];
+
+/** The currently matched route, or null if no route matches. */
+declare const currentRoute: _matthesketh_utopia_core.Signal<RouteMatch | null>;
+/** Whether a navigation is currently in progress (loading component, etc.). */
+declare const isNavigating: _matthesketh_utopia_core.Signal<boolean>;
+/**
+ * Initialize the router with a compiled route table.
+ *
+ * This must be called once at application startup. It:
+ * 1. Stores the route table
+ * 2. Matches the current URL and sets `currentRoute`
+ * 3. Sets up popstate listener for browser back/forward
+ * 4. Sets up click listener for <a> interception
+ *
+ * @param routeTable - Array of compiled routes from `buildRouteTable()`
+ */
+declare function createRouter(routeTable: Route[]): void;
+/**
+ * Navigate to a new URL.
+ *
+ * @param url - The URL to navigate to (absolute path like '/about' or full URL)
+ * @param options - Navigation options
+ * @param options.replace - If true, replace the current history entry instead of pushing
+ * @returns Promise that resolves when navigation is complete
+ */
+declare function navigate(url: string, options?: {
+    replace?: boolean;
+}): Promise<void>;
+/** Navigate back one entry in the browser history. */
+declare function back(): void;
+/** Navigate forward one entry in the browser history. */
+declare function forward(): void;
+/**
+ * Register a navigation guard that runs before each navigation.
+ *
+ * The hook receives the current and next route matches. It can:
+ * - Return `void` or `true` to allow navigation
+ * - Return `false` to cancel navigation
+ * - Return a string to redirect to a different URL
+ *
+ * @param hook - The guard callback
+ * @returns A function that removes the hook
+ */
+declare function beforeNavigate(hook: BeforeNavigateHook): () => void;
+/**
+ * Tear down the router, removing all event listeners and clearing state.
+ * Primarily useful for testing and HMR.
+ */
+declare function destroy(): void;
+
+/**
+ * Creates a DOM node that renders the current route's component.
+ *
+ * When the route changes:
+ * 1. The old component is unmounted (removed from DOM)
+ * 2. The new component is lazily loaded
+ * 3. If the route has a layout, the page is wrapped in the layout
+ * 4. If loading fails and an error component exists, it is shown instead
+ *
+ * @returns A container DOM node that manages route component lifecycle
+ *
+ * @example
+ * ```ts
+ * const view = createRouterView();
+ * document.getElementById('app')!.appendChild(view);
+ * ```
+ */
+declare function createRouterView(): Node;
+/**
+ * Creates an anchor element that performs client-side navigation when clicked.
+ *
+ * The link integrates with the router's click interception, but also sets up
+ * the correct `href` and can apply active-state CSS classes.
+ *
+ * @param props - Link properties
+ * @param props.href - The URL to navigate to
+ * @param props.children - Child node(s) to render inside the anchor
+ * @param props.class - Optional CSS class name
+ * @param props.activeClass - Optional CSS class applied when the link's href matches the current route
+ * @returns An HTMLAnchorElement
+ *
+ * @example
+ * ```ts
+ * const link = createLink({
+ *   href: '/about',
+ *   children: document.createTextNode('About'),
+ * });
+ * document.body.appendChild(link);
+ * ```
+ */
+declare function createLink(props: {
+    href: string;
+    children: Node | string;
+    class?: string;
+    activeClass?: string;
+}): HTMLAnchorElement;
+
+export { type BeforeNavigateHook, type Route, type RouteMatch, type RouterState, back, beforeNavigate, buildRouteTable, compilePattern, createLink, createRouter, createRouterView, currentRoute, destroy, filePathToRoute, forward, isNavigating, matchRoute, navigate };