🤖 AI Progress Controls

Production-ready UI components for AI/ML workflows

React • Next.js • Web Components • Drop in with one import

🚀 Why AI Progress Controls?

Stop rebuilding the same AI UI components for every project. Get production-ready components that work with ANY framework:

✨ Developer Experience

⚛️ React & Next.js Ready - Native adapters with hooks & SSR
🎯 One Import Away - Single import, drop in JSX, done
🔌 Web Components - Works everywhere (Vue, Angular, Svelte, plain HTML)
📦 Zero Dependencies - Lightweight and fast (~28KB gzipped)
🎨 Fully Themeable - CSS variables, dark mode ready
📘 TypeScript First - Complete type definitions included

🤖 AI-Aware Features

⚡ Token Streaming - Real-time visualization with rate tracking
💰 Cost Estimation - Built-in pricing calculations
🔄 Retry Logic - Exponential backoff strategies
📊 Queue Management - Position tracking with ETA
🎯 Batch Processing - Concurrency control & item tracking
🎛️ Parameter Controls - Unified LLM configuration panels

🎨 Visual Customization

✅ 4 Visual Variants - default, minimal, gradient, glassmorphic
✅ 4 Animation Effects - none, striped, pulse, glow
✅ 3 Size Variants - compact, default, large
✅ 5 Brand Themes - OpenAI, Anthropic, Google AI, Cohere, Dark
✅ Cursor Feedback - Automatic state indication
✅ Smooth Animations - Hardware-accelerated transitions

🎯 Production Stats

| 7 Components | 10 Examples | 292 Tests | 91.34% Coverage | 0 Errors | | :--------------: | :--------------: | :-----------: | :-----------------: | :-------------: | | Fully documented | Copy-paste ready | 100% passing | Exceeds 80% target | SonarQube clean |

⚡ Quick Start - Choose Your Framework

⚛️ React / Next.js (Recommended)

npm install ai-progress-controls @ai-progress-controls/react

import { StreamProgress } from '@ai-progress-controls/react';

function App() {
  return <StreamProgress maxTokens={2000} />;
}

That's it! Props sync automatically, no refs needed.

📖 React Guide • 📖 Next.js Guide

🌐 Web Components (Universal)

Works in Vue, Angular, Svelte, or plain JavaScript:

import { StreamProgress } from 'ai-progress-controls';

const progress = new StreamProgress({ maxTokens: 2000 });
document.body.appendChild(progress);

That's it! Import, create, append - works in any framework.

📖 Getting Started • 🎮 Examples

📚 Documentation

⚛️ React Adapter • ▲ Next.js Adapter • 🌐 Web Components • 📚 API Docs

Code Examples:
⚛️ React Examples • ▲ Next.js Examples • 🎮 Vanilla JS Examples

📦 Framework Integration

Choose the best package for your stack

⚛️ React

npm install @ai-progress-controls/react

Features:

• ✅ Hooks-based API
• ✅ Props sync automatically
• ✅ TypeScript support
• ✅ React 18+ compatible

📖 React Documentation

▲ Next.js

npm install @ai-progress-controls/next

Features:

• ✅ Full SSR support
• ✅ App Router ready
• ✅ No hydration errors
• ✅ Auto client components

📖 Next.js Documentation

🌐 Web Components

npm install ai-progress-controls

Features:

• ✅ Framework-agnostic
• ✅ Vue, Angular, Svelte
• ✅ Plain JavaScript
• ✅ Zero dependencies

📖 Web Components Guide

🎮 Live Demo

git clone https://github.com/Maneesh-Relanto/ai-progress-controls.git
cd ai-progress-controls
npm install
npm run dev

🌐 Open http://localhost:5173

| 🏠 Homepage | 📚 Examples Gallery | | :---------------------------------------------------: | :---------------------------------------------: | | Interactive demos of all 7 components | 10 copy-paste examples |

💡 Pro Tip: Open index.html directly in your browser to see all components in action!

📦 What's Included

🎯 7 Production-Ready Components

🌊 StreamProgress

Real-time token streaming visualization

✓ Rate tracking (tokens/sec)
✓ Cost estimation
✓ Live progress updates

📖 Docs • 🎮 Demo

📥 ModelLoader

Multi-stage model loading

✓ Download progress
✓ Memory usage tracking
✓ Per-stage ETA

📖 Docs • 🎮 Demo

🎛️ ParameterSlider

Single LLM parameter control

✓ Temperature, top-p, etc.
✓ Preset configurations
✓ Manual input support

📖 Docs • 🎮 Demo

🎚️ ParameterPanel 🆕

Multi-parameter configuration

✓ Grouped controls
✓ Preset management
✓ Export/import configs
✓ Custom validation

📖 Docs • 🎮 Demo

⏳ QueueProgress

Queue position tracking

✓ Live position updates
✓ ETA calculation
✓ Processing rate

📖 Docs • 🎮 Demo

🔄 RetryProgress

Exponential backoff retry

✓ 4 retry strategies
✓ Automatic retry logic
✓ Error handling

📖 Docs • 🎮 Demo

📊 BatchProgress

Batch processing progress

✓ Multiple items
✓ Concurrency control
✓ Individual tracking

📖 Docs • 🎮 Demo

📚 Complete Documentation

| 📖 Getting Started | 🎮 28+ Examples | 📘 API Reference | 🎨 Theming Guide | | :--------------------------------------------: | :----------------------------------------: | :------------------------------: | :--------------: | | Quick setup guide | 4-6 per component | 1,100+ lines each | CSS variables |

🎯 Problem & Solution

❌ The Problem

Developers building AI apps face repetitive UI challenges:

• 🔴 Generic progress bars don't show AI context (tokens, costs, queues)
• 🔴 Manual implementation of LLM controls = inconsistent UX
• 🔴 No standard components for AI operations
• 🔴 Framework lock-in forces rebuilding for React/Vue/Angular
• 🔴 Poor DX integrating with streaming AI APIs

✅ Our Solution

Specialized UI components built FOR AI workflows:

• 🟢 AI-aware components with token tracking, cost estimation
• 🟢 Production-ready - just import and use
• 🟢 Works everywhere - framework-agnostic Web Components
• 🟢 Zero dependencies - lightweight and fast
• 🟢 TypeScript first - complete type safety

👥 Target Audience

Frontend & Fullstack developers building AI-powered applications

🎯 Primary Users

• 🤖 Developers integrating OpenAI/Anthropic/other LLM APIs
• 🏢 Teams building internal AI tools and dashboards
• 💼 Indie hackers creating AI SaaS products
• 🔬 ML engineers adding UIs to inference pipelines
• 🛠️ Developer tool creators building AI-enhanced IDEs

💡 Use Cases

• 💬 Chatbot interfaces with streaming responses
• 🖼️ Image generation tools (Stable Diffusion, DALL-E)
• 📄 Batch document processing systems
• ✍️ AI content creation platforms
• 🎛️ Model fine-tuning dashboards
• 🎤 Voice/audio transcription services

📊 Project Status

🚀 v0.1.0 - Production Ready

✅ Completed

🎯 Components (7/7)

• ✅ StreamProgress - Token streaming
• ✅ ModelLoader - Multi-stage loading
• ✅ ParameterSlider - LLM controls
• ✅ QueueProgress - Queue tracking
• ✅ RetryProgress - Retry logic
• ✅ BatchProgress - Batch processing

📚 Documentation

• ✅ 10 interactive examples (visual variants, theming, cursor states)
• ✅ Complete API docs (400+ lines each)
• ✅ Getting started guide
• ✅ TypeScript definitions
• ✅ Visual variants guide

✅ Testing & Quality Assurance

292 tests • 100% pass rate • ~7.2s execution time

📊 Test Coverage by Component

| Component | Tests | Status | | ------------------ | :-----: | :---------: | | 🎛️ ParameterPanel | 55 | ✅ | | 🌊 StreamProgress | 49 | ✅ | | 📊 BatchProgress | 46 | ✅ | | 🔄 RetryProgress | 40 | ✅ | | ⏳ QueueProgress | 36 | ✅ | | 🎛️ ParameterSlider | 34 | ✅ | | 📥 ModelLoader | 32 | ✅ | | TOTAL | 292 | ✅ 100% |

🧪 What's Tested

✅ Lifecycle Methods - start, update, complete, cancel, reset
✅ Event Emission - All custom events verified
✅ State Management - State transitions & accuracy
✅ Properties - Getters, setters, disabled states
✅ Rendering - Shadow DOM & dynamic updates
✅ Accessibility - ARIA attributes & roles
✅ Edge Cases - Boundary values, rapid operations
✅ Validation - Custom validation functions
✅ Persistence - localStorage save/load

🔬 Test Framework: Vitest with jsdom • ⚡ Fast: ~7.2s for 292 tests • 🎯 Comprehensive: Every public API + visual variants tested

Run Tests: npm test

🚧 Next Steps

| Priority | Task | Status | | :-------: | ------------------------------------- | :-----: | | 🔴 High | npm package publishing | Ready | | 🟡 Medium | Documentation website (GitHub Pages) | Planned | | 🟡 Medium | E2E tests | Planned | | 🟢 Low | Additional components (6+ identified) | Roadmap |

🔥 Framework Support - Works Everywhere!

One component. Any framework. Zero configuration.

⚛️ React / Next.js

import { StreamProgress } from 'ai-progress-controls';
const progress = new StreamProgress();
containerRef.current.appendChild(progress);

💚 Vue / Nuxt

import { StreamProgress } from 'ai-progress-controls'; const progress = new StreamProgress();
container.value.appendChild(progress);

🅰️ Angular

import { StreamProgress } from 'ai-progress-controls';
const progress = new StreamProgress();
this.container.nativeElement.appendChild(progress);

🧡 Svelte / SvelteKit

import { StreamProgress } from 'ai-progress-controls';
const progress = new StreamProgress();
container.appendChild(progress);

🟦 SolidJS

import { StreamProgress } from 'ai-progress-controls';
const progress = new StreamProgress();
container?.appendChild(progress);

⚡ Vanilla JS

import { StreamProgress } from 'ai-progress-controls';
const progress = new StreamProgress();
document.body.appendChild(progress);

Also works with: Preact • Lit • Astro • Qwik • Ember • And any other JavaScript framework!

📖 See full framework examples

🎨 Features

🏗️ Architecture

✅ Web Components (native browser standard)
✅ Shadow DOM encapsulation
✅ Zero dependencies
✅ ~28KB gzipped (all 7 components)
✅ TypeScript strict mode

🎯 AI-Specific

✅ Token counting & rate tracking
✅ Cost estimation ($/token)
✅ Queue position & ETA
✅ Retry strategies (4 types)
✅ Batch concurrency control

♿ Accessibility

✅ WCAG AA compliant (4.5:1 contrast)
✅ ARIA attributes & roles
✅ Keyboard navigation support
✅ Screen reader optimized
✅ Focus management

🎨 Theming

✅ CSS custom properties
✅ Dark mode ready
✅ Reduced motion support
✅ High contrast mode
✅ Fully customizable

🛣️ Roadmap

✅ Phase 1

Core Architecture

✅ Web Components
✅ TypeScript setup
✅ Build pipeline
✅ Dev environment

✅ Phase 2

Components

✅ StreamProgress
✅ ModelLoader
✅ ParameterSlider
✅ QueueProgress
✅ RetryProgress
✅ BatchProgress
✅ ParameterPanel 🆕

✅ Phase 3

Visual Variants & Animations 🎨

✅ 4 Visual Variants (default, minimal, gradient, glassmorphic)
✅ 4 Animation Effects (none, striped, pulse, glow)
✅ 3 Size Variants (compact, default, large)
✅ Cursor States (auto-updating based on component state)
✅ 48 additional tests (292 total)

✅ Phase 4

Documentation & Examples 📚

✅ 10 Examples - Interactive demos
✅ 7 API Docs - Complete references
✅ Visual Variants Guide - Customization
✅ Theming Guide - CSS variables
✅ Getting Started - Quick setup

🔮 Future Components

• 🔄 WorkflowProgress - Multi-step AI pipeline visualization
• 📊 ConfidenceThreshold - Adjustable confidence sliders with previews
• 🎯 ModelComparison - Side-by-side model performance comparison
• 📈 MetricsDisplay - Real-time metrics dashboard for AI operations
• 📤 FileUploadProgress - Drag-drop file uploads for AI processing
• 🎵 TranscriptionProgress - Real-time audio transcription visualization

�️ Quality & Testing

We maintain enterprise-grade quality standards with multiple layers of automated validation:

| Validation | Tool | Status | Metric | | :------------------: | :--------------: | :----: | :-------------------: | | 🧪 Unit Tests | Vitest | ✅ | 292 tests passing | | 📊 Coverage | Vitest | ✅ | 91.34% (target: 80%) | | 🔒 Type Safety | TypeScript | ✅ | Strict mode, 0 errors | | ✨ Code Quality | SonarQube | ✅ | 0 critical issues | | 🎨 Formatting | Prettier | ✅ | Auto-formatted | | ⚡ Performance | Lighthouse | ✅ | 95+ scores | | ♿ Accessibility | Axe + Lighthouse | ✅ | WCAG 2.1 AA | | 🔐 Security | npm audit | ✅ | 0 vulnerabilities |

📖 View Full Quality Guide

📖 Documentation

| Resource | Description | Link | | :--------------------: | -------------------------------- | :---------------------------------------------: | | 📘 Getting Started | Setup guide for all frameworks | View | | 📚 API Reference | Complete API docs (7 components) | View | | 🎮 Examples | 10 interactive examples | View | | 🎨 Visual Variants | Customization & animations | View | | 🖌️ Theming Guide | CSS variables & brand themes | View | | ♿ Accessibility | WCAG compliance details | View |

🤝 Contributing

Contributions welcome! This is an open-source project aimed at improving DX for AI application developers.

Report Issues • Suggest Features • Submit PRs

📄 License

MIT License - See LICENSE file for details

Copyright © 2026 Maneesh Thakur

Built with ❤️ for the AI developer community

⭐ Star this repo if you find it useful! ⭐