@openwebf/react-router 0.22.18 → 0.24.0

package/dist/index.d.ts

@@ -2,6 +2,8 @@ import React, { SyntheticEvent, EventHandler, ReactNode, FC } from 'react';
 import { WebFElementWithMethods } from '@openwebf/react-core-ui';
 
 type RoutePath = string;
+type EnsureRouteMountedCallback = (pathname: string) => Promise<void> | void;
+declare function __unstable_setEnsureRouteMountedCallback(callback: EnsureRouteMountedCallback | null): void;
 /**
  * Single entry in the hybrid router stack.
  * Mirrors the data returned from webf.hybridHistory.buildContextStack.
@@ -27,7 +29,7 @@ declare const WebFRouter: {
     /**
      * Get the current route path
      */
-    readonly path: RoutePath;
+    readonly path: string;
     /**
      * Navigate to a specified route
      * Applies route guards for permission checks before navigation
@@ -91,6 +93,43 @@ declare const WebFRouter: {
      */
     restorablePopAndPushNamed: <T extends RoutePath>(path: T, state?: any) => Promise<string>;
 };
+/**
+ * Route parameters extracted from dynamic routes
+ */
+interface RouteParams {
+    [key: string]: string;
+}
+/**
+ * Route match result
+ */
+interface RouteMatch {
+    path: string;
+    params: RouteParams;
+    isExact: boolean;
+}
+/**
+ * Convert a route pattern to a regular expression
+ * @param pattern Route pattern like "/user/:userId" or "/category/:catId/product/:prodId"
+ * @returns Object with regex and parameter names
+ */
+declare function pathToRegex(pattern: string): {
+    regex: RegExp;
+    paramNames: string[];
+};
+/**
+ * Match a pathname against a route pattern and extract parameters
+ * @param pattern Route pattern like "/user/:userId"
+ * @param pathname Actual pathname like "/user/123"
+ * @returns Match result with extracted parameters or null if no match
+ */
+declare function matchPath(pattern: string, pathname: string): RouteMatch | null;
+/**
+ * Find the best matching route from a list of route patterns
+ * @param routes Array of route patterns
+ * @param pathname Current pathname
+ * @returns Best match or null if no routes match
+ */
+declare function matchRoutes(routes: string[], pathname: string): RouteMatch | null;
 
 /**
  * Route Component
@@ -116,6 +155,11 @@ interface RouteProps {
      * Must be a member of the RoutePath enum
      */
     path: string;
+    /**
+     * The concrete path to mount for this route instance.
+     * Used internally to support dynamic routes like `/users/:id` mounting at `/users/123`.
+     */
+    mountedPath?: string;
     /**
      * Whether to pre-render
      * If true, the page will be rendered when the app starts, rather than waiting for route navigation
@@ -129,13 +173,20 @@ interface RouteProps {
      * The actual page component to render
      */
     element: React.ReactNode;
+    /**
+     * Theme for this route
+     * Controls the visual style of the navigation bar and page
+     *
+     * @default "material"
+     */
+    theme?: 'material' | 'cupertino';
 }
 /**
  * Route Component
  *
  * Responsible for managing page rendering, lifecycle and navigation bar
  */
-declare function Route({ path, prerender, element, title }: RouteProps): React.JSX.Element;
+declare function Route({ path, mountedPath, prerender, element, title, theme }: RouteProps): React.JSX.Element;
 
 /**
  * Hook to get route context
@@ -157,11 +208,19 @@ declare function useRouteContext(): {
      * Current route path, corresponds to RoutePath enum
      */
     path: string | undefined;
+    /**
+     * The concrete mounted path for this route instance (e.g. `/users/123`).
+     */
+    mountedPath: string | undefined;
     /**
      * Page state
      * State data passed during route navigation
      */
     params: any;
+    /**
+     * Route parameters extracted from dynamic routes (e.g., :userId in /user/:userId)
+     */
+    routeParams: RouteParams | undefined;
     /**
      * Current active path from router
      */
@@ -199,6 +258,7 @@ interface Location {
  *   const location = useLocation();
  *
  *   console.log('Current path:', location.pathname);
+
  *   console.log('Location state:', location.state);
  *   console.log('Is active:', location.isActive);
  *
@@ -209,6 +269,24 @@ interface Location {
 declare function useLocation(): Location & {
     isActive: boolean;
 };
+/**
+ * Hook to get route parameters from dynamic routes
+ *
+ * @returns Route parameters object with parameter names as keys and values as strings
+ *
+ * @example
+ * ```tsx
+ * // For route pattern "/user/:userId" and actual path "/user/123"
+ * function UserPage() {
+ *   const params = useParams();
+ *
+ *   console.log(params.userId); // "123"
+ *
+ *   return <div>User ID: {params.userId}</div>;
+ * }
+ * ```
+ */
+declare function useParams(): RouteParams;
 /**
  * Route configuration object
  */
@@ -225,6 +303,12 @@ interface RouteObject {
      * Whether to pre-render this route
      */
     prerender?: boolean;
+    /**
+     * Theme for this route
+     *
+     * @default "material"
+     */
+    theme?: 'material' | 'cupertino';
     /**
      * Child routes (not supported yet)
      */
@@ -350,6 +434,7 @@ type HybridRouterChangeEventHandler = EventHandler<HybridRouterChangeEvent>;
 interface WebFHybridRouterProps {
     path: string;
     title?: string;
+    theme?: 'material' | 'cupertino';
     onScreen?: HybridRouterChangeEventHandler;
     offScreen?: HybridRouterChangeEventHandler;
     children?: ReactNode;
@@ -358,5 +443,5 @@ interface WebFRouterLinkElement extends WebFElementWithMethods<{}> {
 }
 declare const WebFRouterLink: FC<WebFHybridRouterProps>;
 
-export { Route, Routes, WebFRouter, WebFRouterLink, useLocation, useNavigate, useRouteContext, useRoutes };
-export type { HybridRouteStackEntry, HybridRouterChangeEvent, HybridRouterChangeEventHandler, Location, NavigateFunction, NavigateOptions, NavigationMethods, RouteObject, RouteProps, RoutesProps, WebFHybridRouterProps, WebFRouterLinkElement };
+export { Route, Routes, WebFRouter, WebFRouterLink, __unstable_setEnsureRouteMountedCallback, matchPath, matchRoutes, pathToRegex, useLocation, useNavigate, useParams, useRouteContext, useRoutes };
+export type { HybridRouteStackEntry, HybridRouterChangeEvent, HybridRouterChangeEventHandler, Location, NavigateFunction, NavigateOptions, NavigationMethods, RouteMatch, RouteObject, RouteParams, RouteProps, RoutesProps, WebFHybridRouterProps, WebFRouterLinkElement };