tessl/npm-mantine--nprogress

Navigation progress bar component for React applications with Mantine UI framework integration

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Progress State Management

Name: tessl/npm-mantine--nprogress
Author: tessl

The progress state management system provides the core store functionality for tracking progress state, managing intervals and timeouts, and enabling React integration through hooks.

Capabilities

Store Creation

Factory function for creating new progress store instances.

/**
 * Creates a new progress store with default initial state
 * @returns New NprogressStore instance
 */
function createNprogressStore(): NprogressStore;

Usage Examples:

import { createNprogressStore, useNprogress } from "@mantine/nprogress";

// Create isolated store for specific component
const myStore = createNprogressStore();

// Use in React component
function MyComponent() {
  const state = useNprogress(myStore);
  
  return (
    <div>
      Progress: {state.progress}%
      {state.mounted && <div>Progress bar is visible</div>}
    </div>
  );
}

React Hook Integration

Hook for subscribing to store state changes in React components.

/**
 * React hook to subscribe to progress store state changes
 * @param store - The progress store to subscribe to
 * @returns Current state of the progress store
 */
function useNprogress(store: NprogressStore): NprogressState;

Usage Examples:

import { useNprogress, nprogressStore } from "@mantine/nprogress";

// Using default store
function ProgressDisplay() {
  const state = useNprogress(nprogressStore);
  
  return (
    <div>
      <div>Current Progress: {state.progress}%</div>
      <div>Mounted: {state.mounted ? 'Yes' : 'No'}</div>
      <div>Step Interval: {state.stepInterval}ms</div>
    </div>
  );
}

// Using custom store
import { createNprogressStore } from "@mantine/nprogress";

const customStore = createNprogressStore();

function CustomProgressDisplay() {
  const state = useNprogress(customStore);
  // ... use state
}

Default Store Instance

Pre-created global store instance for simple usage scenarios.

/** Default shared store instance for global progress control */
const nprogressStore: NprogressStore;

Usage Examples:

import { nprogressStore, useNprogress } from "@mantine/nprogress";

// Direct store access
console.log(nprogressStore.getState());

// React hook usage
function GlobalProgressMonitor() {
  const state = useNprogress(nprogressStore);
  return <div>Global Progress: {state.progress}%</div>;
}

Low-Level State Updates

Low-level function for updating store state with custom logic.

/**
 * Updates progress store state using a partial state updater function
 * @param update - Function that receives current state and returns partial state update
 * @param store - The progress store to update
 */
function updateNavigationProgressStateAction(
  update: (state: NprogressState) => Partial<NprogressState>,
  store: NprogressStore
): void;

Usage Examples:

import { updateNavigationProgressStateAction, nprogressStore } from "@mantine/nprogress";

// Custom state update
updateNavigationProgressStateAction(
  (state) => ({ 
    progress: Math.min(state.progress + 25, 100),
    mounted: true 
  }),
  nprogressStore
);

// Conditional state update
updateNavigationProgressStateAction(
  (state) => {
    if (state.progress >= 90) {
      return { progress: 100, mounted: false };
    }
    return { progress: state.progress + 10 };
  },
  nprogressStore
);

Types

/** Progress store state structure */
interface NprogressState {
  /** Whether the progress bar is currently visible */
  mounted: boolean;
  
  /** Current progress value (0-100) */
  progress: number;
  
  /** Window interval ID for automatic progress increments */
  interval: number;
  
  /** Progress increment step size */
  step: number;
  
  /** Time between automatic progress increments in milliseconds */
  stepInterval: number;
  
  /** Array of active timeout IDs for cleanup */
  timeouts: number[];
}

/** Progress store type extending Mantine's store system */
type NprogressStore = MantineStore<NprogressState>;

Default State Values

When creating a new store with createNprogressStore(), the following default values are used:

{
  mounted: false,
  progress: 0,
  interval: 0,
  step: 1,
  stepInterval: 100,  // Note: NavigationProgress component defaults to 500ms
  timeouts: []
}

Important: The NavigationProgress component uses a default stepInterval of 500ms in its props, which overwrites the store default when the component initializes the store.

State Management Patterns

Reading State:

// Get current state snapshot
const currentState = store.getState();

// Subscribe to state changes in React
const state = useNprogress(store);

Updating State:

// Direct state replacement
store.setState({ progress: 50, mounted: true });

// Partial state update with merge
updateNavigationProgressStateAction(
  (state) => ({ progress: state.progress + 10 }),
  store
);

Cleanup Management:

// Store tracks timeouts for proper cleanup
updateNavigationProgressStateAction(
  (state) => {
    const timeout = setTimeout(() => {
      // Some delayed action
    }, 1000);
    
    return {
      timeouts: [...state.timeouts, timeout]
    };
  },
  store
);