/**
 * Navigation-aware request cancellation context.
 *
 * Provides a global cancellation mechanism tied to route transitions.
 * When the user navigates to a new route, all AbortSignals obtained from
 * this context are automatically aborted, cancelling in-flight requests
 * associated with the previous route.
 *
 * Long-lived background fetches (e.g., polling with long TTL) can opt-out
 * by not using this context and instead managing their own lifecycle,
 * or by checking the signal early in their lifecycle.
 *
 * Design notes:
 * - Subscribers are notified immediately when navigation occurs
 * - Multiple consumers can safely subscribe and get independent signals
 * - Signals are generator functions to allow late binding
 */

import { createContext } from "react";

/**
 * Provides a fresh AbortSignal tied to the current route lifecycle.
 *
 * Each call returns a new AbortSignal. When the user navigates,
 * all previously-returned signals are aborted.
 */
export interface NavigationCancellationContextType {
  /**
   * Get an AbortSignal for the current route's request lifecycle.
   *
   * The signal will be aborted automatically when the user navigates
   * to a different route. This is ideal for route-specific data fetches
   * that should not persist across page transitions.
   *
   * Example:
   *   const signal = useNavigationAbortSignal();
   *   const { items } = useListData({
   *     fetcher: (sig) => fetchBans(sig || signal),
   *     // ...
   *   });
   *
   * @returns An AbortSignal that lives for the duration of the current route
   */
  getNavigationSignal(): AbortSignal;
}

/**
 * React context for navigation-aware cancellation.
 *
 * Wrap the application with `NavigationCancellationProvider` to enable
 * automatic request cancellation on route transitions.
 */
export const NavigationCancellationContext =
  createContext<NavigationCancellationContextType | null>(null);

NavigationCancellationContext.displayName = "NavigationCancellation";