defuss 3.4.1 → 3.4.3

package/dist/index.d.ts

@@ -137,6 +137,60 @@ declare const T: ({ key, values, tag, ref, ...attrs }: TransProps<string>) => VN
 type OnHandleRouteChangeFn = (newRoute: string, oldRoute: string) => void;
 type OnRouteChangeFn = (cb: OnHandleRouteChangeFn) => void;
 type RouterStrategy = "page-refresh" | "slot-refresh";
+type BeforeUnmountHookFn = () => boolean | void | Promise<boolean | void>;
+type UnmountHookFn = () => void;
+/**
+ * Context object passed to components rendered via Route's `component` prop.
+ * Provides access to the current route request and lifecycle hooks.
+ *
+ * @example
+ * ```tsx
+ * const MyScreen = ({ route }: { route: RouteContext }) => {
+ *   route.onBeforeUnmount(() => {
+ *     // Return false to block navigation (e.g. unsaved changes)
+ *     return confirm("Leave page?");
+ *   });
+ *   route.onUnmount(() => {
+ *     console.log("Route was left");
+ *   });
+ *   return <div>Current path: {route.request.path}</div>;
+ * };
+ * ```
+ */
+interface RouteContext {
+    /** The matched RouteRequest for the current route */
+    request: RouteRequest;
+    /**
+     * Register a hook that fires before the route is unmounted.
+     * Returning `false` (or a Promise resolving to `false`) blocks navigation,
+     * allowing implementation of confirmation dialogs.
+     */
+    onBeforeUnmount(fn: BeforeUnmountHookFn): void;
+    /**
+     * Register a hook that fires after the route has been unmounted
+     * (navigation completed, new route is rendered).
+     */
+    onUnmount(fn: UnmountHookFn): void;
+}
+/**
+ * Props mixin for screen components rendered by `<Route component={...} />`.
+ * Extend your component props with this to get typed access to route context.
+ *
+ * @example
+ * ```tsx
+ * import { Router, type Props, type RouteProps } from "defuss";
+ *
+ * export interface ProjectDetailsProps extends Props, RouteProps {}
+ *
+ * export function ProjectDetailsScreen({ route }: ProjectDetailsProps) {
+ *   const { projectName } = route.request.params;
+ *   return <h1>Project: {projectName}</h1>;
+ * }
+ * ```
+ */
+interface RouteProps {
+    route: RouteContext;
+}
 interface RouterConfig {
     strategy?: RouterStrategy;
 }
@@ -268,6 +322,10 @@ interface RouterState {
     pendingResolvers: Array<() => void>;
     currentPath: string;
     popAttached: boolean;
+    lifecycleHooks: {
+        beforeUnmount: Array<BeforeUnmountHookFn>;
+        unmount: Array<UnmountHookFn>;
+    };
 }
 declare global {
     var __defuss_router__: Router | undefined;
@@ -301,17 +359,49 @@ interface Router {
      * ```
      */
     ready(): Promise<void>;
+    /**
+     * Create a RouteContext object for a matched route request.
+     * The context provides lifecycle hooks (onBeforeUnmount, onUnmount)
+     * and is passed to components rendered via Route's `component` prop.
+     */
+    createRouteContext(request: RouteRequest): RouteContext;
 }
 declare const Router: Router;
 
-interface RouteProps extends Props {
+interface RouteComponentProps extends Props {
     path: string;
     router?: Router;
     exact?: boolean;
+    /**
+     * A component function to render when this route matches.
+     * Unlike children (which are eagerly evaluated by the JSX runtime),
+     * the component function is called **lazily** — only after the route
+     * has been registered and matched. This ensures `Router.getRequest()`
+     * returns the correct params inside the component.
+     *
+     * The component receives a `route` prop (RouteContext) with:
+     * - `route.request` — the matched RouteRequest with params, query, etc.
+     * - `route.onBeforeUnmount(fn)` — register a hook before route leaves; return `false` to block
+     * - `route.onUnmount(fn)` — register a hook after route has been left
+     *
+     * When the component is async and Route has children, the children are
+     * shown as a loading fallback until the async component resolves.
+     *
+     * @example
+     * ```tsx
+     * <Route path="/project/:projectName" component={ProjectDetailsScreen} />
+     *
+     * // With loading fallback for async components:
+     * <Route path="/dashboard" component={AsyncDashboard}>
+     *   <Spinner />
+     * </Route>
+     * ```
+     */
+    component?: FC<any>;
 }
-declare const Route: FC<RouteProps>;
+declare const Route: FC<RouteComponentProps>;
 
-interface RedirectProps extends RouteProps {
+interface RedirectProps extends RouteComponentProps {
     to: string;
 }
 declare const Redirect: FC<RedirectProps>;
@@ -396,4 +486,4 @@ declare const Suspense: ({ fallback, ref, children, class: _class, className, id
 };
 
 export { Async, AsyncDefussChild, DOMElement, FC, Globals, NodeType, PersistenceProviderImpl, PersistenceProviderOptions, PersistenceProviderType, Props, Redirect, Ref, RenderInput, Route, Router, RouterSlot, RouterSlotId, Suspense, T, Trans, TransitionConfig, VNode, VNodeAttributes, VNodeChild, addElementEvent, areDomNodesEqual, changeLanguage, checkElementVisibility, clearElementEvents, createI18n, createTrans, domNodeToVNode, getEventMap, getLanguage, getMimeType, getRouterState, htmlStringToVNodes, i18n, inDevMode, isHTML, isMarkup, isSVG, loadLanguage, matchRouteRegistrations, parseDOM, processAllFormElements, queueCallback, removeElementEvent, renderMarkup, replaceDomWithVdom, setupRouter, t, tokenizePath, updateDomWithVdom, waitForDOM, webstorage };
-export type { AsyncProps, AsyncState, AsyncStateRef, I18nStore, MatchRouteRegistrationsOpts, OnHandleRouteChangeFn, OnLanguageChangeListener, OnRouteChangeFn, RedirectProps, Replacements, Resolve, RouteHandler, RouteParams, RouteProps, RouteRegistration, RouteRequest, RouterConfig, RouterSlotProps, RouterStrategy, TokenizedPath, TransProps, TransRef, TranslationKeys, TranslationObject, Translations, ValidChild };
+export type { AsyncProps, AsyncState, AsyncStateRef, BeforeUnmountHookFn, I18nStore, MatchRouteRegistrationsOpts, OnHandleRouteChangeFn, OnLanguageChangeListener, OnRouteChangeFn, RedirectProps, Replacements, Resolve, RouteComponentProps, RouteContext, RouteHandler, RouteParams, RouteProps, RouteRegistration, RouteRequest, RouterConfig, RouterSlotProps, RouterStrategy, TokenizedPath, TransProps, TransRef, TranslationKeys, TranslationObject, Translations, UnmountHookFn, ValidChild };