Imperative Progress Control

/**
 * Starts automatic progress increments using intervals
 * Progress speed varies: fast initially (10), then slower as it approaches completion
 */
function startNavigationProgress(): void;

import { startNavigationProgress } from "@mantine/nprogress";

// Start progress on navigation
function handleRouteChange() {
  startNavigationProgress();
}

// Integration with Next.js router
import { useRouter } from "next/router";

function useProgressOnRouteChange() {
  const router = useRouter();
  
  useEffect(() => {
    const handleStart = () => startNavigationProgress();
    router.events.on('routeChangeStart', handleStart);
    
    return () => router.events.off('routeChangeStart', handleStart);
  }, [router]);
}

/**
 * Stops automatic progress increments by clearing the interval
 * Progress value remains at current position
 */
function stopNavigationProgress(): void;

import { stopNavigationProgress } from "@mantine/nprogress";

// Stop progress on user action
function handleUserPause() {
  stopNavigationProgress();
}

// Conditional stopping
function handleConditionalStop(shouldStop: boolean) {
  if (shouldStop) {
    stopNavigationProgress();
  }
}

/**
 * Sets progress to a specific value and makes progress bar visible
 * @param value - Progress value (automatically clamped to 0-100 range)
 */
function setNavigationProgress(value: number): void;

import { setNavigationProgress } from "@mantine/nprogress";

// Set specific progress value
setNavigationProgress(45);

// Track upload progress
function handleUploadProgress(progressEvent: ProgressEvent) {
  const percentComplete = (progressEvent.loaded / progressEvent.total) * 100;
  setNavigationProgress(percentComplete);
}

// Step-by-step progress
const steps = ['Loading', 'Processing', 'Finalizing'];
function updateStepProgress(currentStep: number) {
  const progress = ((currentStep + 1) / steps.length) * 100;
  setNavigationProgress(progress);
}

/**
 * Increases progress by the step amount (default 1)
 * Automatically handles completion and reset when reaching 100%
 */
function incrementNavigationProgress(): void;

import { incrementNavigationProgress } from "@mantine/nprogress";

// Manual progress increments
function handleTaskCompletion() {
  incrementNavigationProgress();
}

// Batch processing progress
async function processBatch(items: any[]) {
  for (const item of items) {
    await processItem(item);
    incrementNavigationProgress();
  }
}

/**
 * Decreases progress by the step amount, minimum value is 0
 */
function decrementNavigationProgress(): void;

import { decrementNavigationProgress } from "@mantine/nprogress";

// Handle progress reversal
function handleUndo() {
  decrementNavigationProgress();
}

// Error handling with progress rollback
function handleProcessingError() {
  decrementNavigationProgress();
  console.log("Process failed, rolling back progress");
}

/**
 * Sets progress to 100%, waits briefly, then hides and resets
 * Includes automatic cleanup of intervals and timeouts
 */
function completeNavigationProgress(): void;

import { completeNavigationProgress } from "@mantine/nprogress";

// Complete progress on successful navigation
function handleRouteChangeComplete() {
  completeNavigationProgress();
}

// Complete progress after async operation
async function handleAsyncOperation() {
  try {
    await performOperation();
    completeNavigationProgress();
  } catch (error) {
    resetNavigationProgress();
  }
}

// Integration with fetch requests
async function handleApiRequest() {
  startNavigationProgress();
  
  try {
    const response = await fetch('/api/data');
    const data = await response.json();
    completeNavigationProgress();
    return data;
  } catch (error) {
    resetNavigationProgress();
    throw error;
  }
}

/**
 * Immediately resets progress to 0, hides progress bar, and cleans up
 * Clears all active intervals and timeouts
 */
function resetNavigationProgress(): void;

import { resetNavigationProgress } from "@mantine/nprogress";

// Reset on navigation error
function handleNavigationError() {
  resetNavigationProgress();
}

// Reset on component unmount
useEffect(() => {
  return () => resetNavigationProgress();
}, []);

/**
 * Clears active intervals and timeouts for resource cleanup
 * Progress value and visibility state remain unchanged
 */
function cleanupNavigationProgress(): void;

import { cleanupNavigationProgress } from "@mantine/nprogress";

// Manual cleanup before component unmount
function handleComponentCleanup() {
  cleanupNavigationProgress();
}

// Cleanup before starting new progress sequence
function handleNewSequence() {
  cleanupNavigationProgress();
  startNavigationProgress();
}

import { 
  startNavigationProgress, 
  completeNavigationProgress, 
  resetNavigationProgress 
} from "@mantine/nprogress";

// Next.js integration
router.events.on('routeChangeStart', startNavigationProgress);
router.events.on('routeChangeComplete', completeNavigationProgress);
router.events.on('routeChangeError', resetNavigationProgress);

// React Router integration (with history)
history.listen(() => {
  startNavigationProgress();
  // Complete when component loads
  setTimeout(completeNavigationProgress, 100);
});

async function trackAsyncOperation<T>(operation: () => Promise<T>): Promise<T> {
  startNavigationProgress();
  
  try {
    const result = await operation();
    completeNavigationProgress();
    return result;
  } catch (error) {
    resetNavigationProgress();
    throw error;
  }
}

// Usage
await trackAsyncOperation(async () => {
  const data = await fetchUserData();
  await processUserData(data);
  return data;
});

// Step-by-step progress tracking
const totalSteps = 5;
let currentStep = 0;

function nextStep() {
  currentStep++;
  const progress = (currentStep / totalSteps) * 100;
  setNavigationProgress(progress);
  
  if (currentStep === totalSteps) {
    setTimeout(completeNavigationProgress, 500);
  }
}