import { Router } from '../types/router';
import { State, NavigationOptions, DoneFn } from '../types/base';
/**
 * Handles the complete transition process between router states.
 *
 * This function orchestrates the entire navigation lifecycle including:
 * - Route deactivation guards (canDeactivate)
 * - Route exit hooks (onExitNode)
 * - Route activation guards (canActivate)
 * - Route enter hooks (onEnterNode)
 * - Active chain hooks (onNodeInActiveChain)
 * - Browser title updates
 * - Middleware execution
 *
 * The transition can be cancelled at any point and includes comprehensive
 * error handling for each phase of the navigation process.
 *
 * @param router - The router instance managing the transition
 * @param toState - The target state to navigate to
 * @param fromState - The current state being navigated from (null for initial navigation)
 * @param opts - Navigation options controlling transition behavior
 * @param callback - Callback function called when transition completes or fails
 * @returns Function to cancel the ongoing transition
 *
 * @example
 * ```typescript
 * const cancelTransition = transition(
 *   router,
 *   targetState,
 *   currentState,
 *   { replace: false },
 *   (err, finalState) => {
 *     if (err) {
 *       console.error('Transition failed:', err)
 *     } else {
 *       console.log('Transition successful:', finalState)
 *     }
 *   }
 * )
 *
 * // Cancel if needed
 * cancelTransition()
 * ```
 */
export default function transition(router: Router, toState: State, fromState: State | null, opts: NavigationOptions, callback: DoneFn): () => void;