abc-progress

A comprehensive progress indicator component library providing animated progress bars, circular progress indicators, and question progress tracking for modern web applications.

📦 Installation

# If using within the monorepo
pnpm add abc-progress

# For external usage
pnpm install abc-progress

🚀 Features

The abc-progress package provides specialized progress components:

• ProgressBar - Animated progress bar with smooth transitions
• CircleProgress - Circular progress indicator with customizable styling
• ProgressQuestion - Question-based progress tracking with Redux integration
• NavigationEvents - Progress management utilities
• Smooth animations - Powered by Framer Motion for fluid transitions
• Redux integration - Built-in state management support
• Customizable styling - Flexible theming and appearance options

📖 Usage

Basic Import

// Import from main entry point
import {
  ProgressBar,
  CircleProgress,
  ProgressQuestion,
  useProgress,
  useProgressBar,
} from "abc-progress";

// Import specific components
import { ProgressBar } from "abc-progress/progressBar";
import { CircleProgress } from "abc-progress/circleProgress";
import { ProgressQuestion } from "abc-progress/progressQuestion";

Usage Examples

1. ProgressBar - Animated Progress Bar

import { ProgressBar, useProgress } from "abc-progress";

const MyComponent = () => {
  const progress = useProgress();

  const handleStart = () => {
    progress.start();
  };

  const handleComplete = () => {
    progress.done();
  };

  return (
    <div>
      <ProgressBar className="h-2 bg-blue-500 rounded-full">
        <div className="p-4">
          <h2>Loading...</h2>
          <p>Progress: {Math.round(progress.value.get())}%</p>
          <button onClick={handleStart}>Start</button>
          <button onClick={handleComplete}>Complete</button>
        </div>
      </ProgressBar>
    </div>
  );
};

Features:

• Smooth spring animations
• Automatic progress simulation
• Context-based state management
• Customizable styling

2. CircleProgress - Circular Progress Indicator

import { CircleProgress } from "abc-progress/circleProgress";

const MyComponent = () => {
  const [progress, setProgress] = useState(0);

  return (
    <div className="flex gap-4">
      {/* Basic circular progress */}
      <CircleProgress
        percentage={progress}
        color="#3b82f6"
        bgColor="#e5e7eb"
        strokeWidth={8}
        size={120}
        showText={true}
      />

      {/* Half circle progress */}
      <CircleProgress
        percentage={75}
        color="#10b981"
        bgColor="#d1fae5"
        strokeWidth={6}
        size={100}
        halfCircle={true}
        showText={false}
        customText={
          <div className="text-center">
            <div className="text-2xl font-bold">75%</div>
            <div className="text-sm text-gray-500">Complete</div>
          </div>
        }
      />

      {/* Custom styled progress */}
      <CircleProgress
        percentage={60}
        color="url(#gradient)"
        bgColor="#f3f4f6"
        strokeWidth={10}
        size={150}
        circleClassName="drop-shadow-lg"
        textClassName="font-bold text-lg"
        textStyles={{ fill: "#1f2937" }}
        wrapperClassName="p-4"
      />
    </div>
  );
};

Features:

• Full and half-circle variants
• Custom text and styling
• SVG-based rendering
• Gradient support
• Responsive sizing

3. ProgressQuestion - Question Progress Tracking

import { ProgressQuestion } from "abc-progress/progressQuestion";
import { Provider } from "react-redux";
import { store } from "./store";

const QuizComponent = () => {
  return (
    <Provider store={store}>
      <div className="quiz-container">
        <h1>Quiz Progress</h1>

        {/* Standard progress bar */}
        <ProgressQuestion />

        {/* Actions variant */}
        <ProgressQuestion isActions={true} />

        {/* Quiz content */}
        <div className="quiz-questions">
          {/* Your quiz questions here */}
        </div>
      </div>
    </Provider>
  );
};

Features:

• Redux state integration
• Correct/incorrect tracking
• Two display variants
• Automatic progress calculation

4. Advanced Usage with Custom Hooks

import {
  ProgressBar,
  useProgress,
  useProgressBar,
  CircleProgress
} from "abc-progress";

const AdvancedProgress = () => {
  const progress = useProgress();
  const progressBar = useProgressBar();

  useEffect(() => {
    // Auto-start progress
    progress.start();

    // Auto-complete after 5 seconds
    const timer = setTimeout(() => {
      progress.done();
    }, 5000);

    return () => clearTimeout(timer);
  }, []);

  return (
    <div className="space-y-6">
      {/* Animated progress bar */}
      <ProgressBar className="h-3 bg-gradient-to-r from-blue-500 to-purple-600 rounded-full">
        <div className="p-6">
          <h2 className="text-xl font-bold mb-2">
            Processing Data...
          </h2>
          <p className="text-gray-600">
            Current progress: {Math.round(progressBar.value.get())}%
          </p>
        </div>
      </ProgressBar>

      {/* Circular progress with custom text */}
      <div className="flex justify-center">
        <CircleProgress
          percentage={progressBar.value.get()}
          color="#8b5cf6"
          bgColor="#f3f4f6"
          strokeWidth={12}
          size={200}
          customText={
            <div className="absolute inset-0 flex items-center justify-center">
              <div className="text-center">
                <div className="text-3xl font-bold text-purple-600">
                  {Math.round(progressBar.value.get())}%
                </div>
                <div className="text-sm text-gray-500">
                  {progressBar.state}
                </div>
              </div>
            </div>
          }
        />
      </div>

      {/* Control buttons */}
      <div className="flex gap-2 justify-center">
        <button
          onClick={() => progress.start()}
          className="px-4 py-2 bg-blue-500 text-white rounded"
        >
          Start
        </button>
        <button
          onClick={() => progress.done()}
          className="px-4 py-2 bg-green-500 text-white rounded"
        >
          Complete
        </button>
        <button
          onClick={() => progress.reset()}
          className="px-4 py-2 bg-gray-500 text-white rounded"
        >
          Reset
        </button>
      </div>
    </div>
  );
};

🏗️ Project Structure

packages/progress/
├── src/
│   ├── circleProgress/     # Circular progress component
│   │   └── index.tsx
│   ├── progressBar/        # Animated progress bar
│   │   ├── index.tsx
│   │   ├── progressBar.tsx
│   │   └── navigationEvents.tsx
│   ├── progressQuestion/   # Question progress tracking
│   │   └── index.tsx
│   └── index.ts           # Main exports
├── dist/                  # Built files
├── package.json
├── tsup.config.ts
└── README.md

🔧 Configuration

Dependencies

The package requires these dependencies:

• framer-motion - Animation library for smooth transitions
• abc-redux - Redux state management integration

Environment Setup

# Install dependencies
pnpm install

# Development mode
pnpm dev

# Build package
pnpm build

# Type checking
pnpm check-types

# Linting
pnpm lint

🎨 Styling

CSS Classes

The components use Tailwind CSS classes and can be customized:

// Custom progress bar styling
<ProgressBar className="h-4 bg-gradient-to-r from-green-400 to-blue-500 rounded-full shadow-lg">
  {/* Content */}
</ProgressBar>

// Custom circle progress styling
<CircleProgress
  circleClassName="drop-shadow-lg"
  textClassName="font-bold text-xl"
  wrapperClassName="p-4 bg-white rounded-lg shadow-md"
/>

Animation Configuration

Customize animations through Framer Motion props:

// Custom spring configuration
const progress = useProgress({
  damping: 30,
  mass: 0.8,
  stiffness: 400,
  restDelta: 0.01,
});

📦 Dependencies

Runtime Dependencies

• framer-motion - Animation and motion library
• abc-redux - Redux state management integration

Development Dependencies

• @repo/eslint-config - Shared ESLint configuration
• TypeScript type definitions

🚀 Development

Prerequisites

• Node.js 18+
• pnpm (recommended package manager)
• React 18+
• Redux (for ProgressQuestion component)

Setup

# Install dependencies
pnpm install

# Build package
pnpm build

# Development mode with watch
pnpm dev

# Clean build artifacts
pnpm clean

# Lint code
pnpm lint

# Type checking
pnpm check-types

📝 API Reference

ProgressBar

Animated progress bar component with context management.

Props:

• className (string) - CSS classes for styling
• children (ReactNode) - Content to display

Context:

• Provides useProgressBar hook for child components

useProgress

Hook for managing progress state and animations.

Returns:

• state - Current progress state ("initial" | "in-progress" | "completing" | "complete")
• value - Spring value for progress percentage
• start() - Start progress animation
• done() - Complete progress animation
• reset() - Reset progress to initial state

CircleProgress

Circular progress indicator component.

Props:

• percentage (number) - Progress percentage (0-100)
• color (string) - Progress color
• bgColor (string) - Background color
• strokeWidth (number) - Stroke width
• size (number) - Circle size
• showText (boolean) - Show percentage text
• halfCircle (boolean) - Render as half circle
• customText (ReactNode) - Custom text content
• textClassName (string) - Text styling classes
• circleClassName (string) - Circle styling classes
• wrapperClassName (string) - Wrapper styling classes

ProgressQuestion

Question-based progress tracking component.

Props:

• isActions (boolean) - Use actions variant styling

Requirements:

• Must be used within Redux Provider
• Requires selectListQuestion selector

🤝 Contributing

1. Fork repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add some amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

📄 License

This project is part of the monorepo and follows the same license terms.

🆘 Support

For support and questions:

• Create an issue in the repository
• Check existing documentation
• Contact the development team

Note: This is an internal UI package designed for use within the monorepo ecosystem. Components are optimized for smooth animations and Redux integration.

📊 Changelog

v0.0.1 (2025-01-11)

• ✅ Initial release with ProgressBar component
• ✅ CircleProgress component with customizable styling
• ✅ ProgressQuestion component with Redux integration
• ✅ Smooth animations powered by Framer Motion
• ✅ Context-based state management
• ✅ TypeScript support with comprehensive types