ai-progress-controls 0.1.0

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "ai-progress-controls",
+  "version": "0.1.0",
+  "description": "Framework-agnostic UI controls for AI/ML workflows - streaming progress, model loading, LLM parameters, and more",
+  "keywords": [
+    "ai",
+    "progress",
+    "slider",
+    "llm",
+    "web-components",
+    "openai",
+    "anthropic",
+    "streaming",
+    "ui-components",
+    "typescript",
+    "framework-agnostic",
+    "accessibility",
+    "developer-friendly"
+  ],
+  "author": "Maneesh Thakur",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Maneesh-Relanto/ai-progress-controls.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Maneesh-Relanto/ai-progress-controls/issues"
+  },
+  "homepage": "https://github.com/Maneesh-Relanto/ai-progress-controls#readme",
+  "main": "dist/ai-progress-controls.umd.js",
+  "module": "dist/ai-progress-controls.es.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "lint": "eslint src --ext .ts,.tsx",
+    "lint:fix": "eslint src --ext .ts,.tsx --fix",
+    "format": "prettier --write \"src/**/*.{ts,tsx,css,md}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx,css,md}\"",
+    "type-check": "tsc --noEmit",
+    "validate": "npm run type-check && npm run lint && npm run format:check && npm run test:coverage",
+    "security:audit": "npm audit --audit-level=moderate",
+    "security:fix": "npm audit fix",
+    "bundle:analyze": "vite build --mode analyze",
+    "lighthouse": "npm run lighthouse:index && npm run lighthouse:examples",
+    "lighthouse:index": "lighthouse http://localhost:5174 --output html --output-path ./lighthouse-reports/index.html --view",
+    "lighthouse:examples": "lighthouse http://localhost:5174/examples/index.html --output html --output-path ./lighthouse-reports/examples.html --view",
+    "lighthouse:ci": "lhci autorun",
+    "prepare": "husky install",
+    "a11y:check": "axe http://localhost:5174 --exit",
+    "deps:check": "depcheck",
+    "deps:update": "ncu -u",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "lint-staged": {
+    "*.{ts,tsx}": [
+      "eslint --fix --ignore-pattern 'test-apps/**' --ignore-pattern 'examples/**' --ignore-pattern 'adapters/**'",
+      "prettier --write"
+    ],
+    "*.{json,md}": [
+      "prettier --write"
+    ]
+  },
+  "devDependencies": {
+    "@axe-core/cli": "^4.11.0",
+    "@lhci/cli": "^0.15.1",
+    "@types/node": "^20.19.28",
+    "@typescript-eslint/eslint-plugin": "^6.13.0",
+    "@typescript-eslint/parser": "^6.13.0",
+    "@vitest/coverage-v8": "^1.6.1",
+    "@vitest/ui": "^1.0.0",
+    "bundle-analyzer": "^0.0.6",
+    "depcheck": "^1.4.7",
+    "eslint": "^8.55.0",
+    "husky": "^9.1.7",
+    "jsdom": "^27.4.0",
+    "lighthouse": "^13.0.1",
+    "lint-staged": "^16.2.7",
+    "npm-check-updates": "^19.3.1",
+    "prettier": "^3.1.0",
+    "terser": "^5.44.1",
+    "typescript": "^5.3.0",
+    "vite": "^5.0.0",
+    "vite-plugin-dts": "^3.6.0",
+    "vitepress": "^1.0.0",
+    "vitest": "^1.0.0",
+    "wait-on": "^9.0.3"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "npm": ">=9.0.0"
+  }
+}

package/src/__tests__/setup.ts

@@ -0,0 +1,93 @@
+/**
+ * Test setup file for Vitest
+ * Configures jsdom environment and utilities for Web Components testing
+ */
+
+import { beforeAll, afterEach, vi } from 'vitest';
+
+// Mock globalThis.customElements if not available
+beforeAll(() => {
+  if (!globalThis.customElements) {
+    // @ts-expect-error - Mock for testing
+    globalThis.customElements = {
+      define: vi.fn(),
+      get: vi.fn(),
+      upgrade: vi.fn(),
+      whenDefined: vi.fn(() => Promise.resolve(class MockElement {} as CustomElementConstructor)),
+    };
+  }
+});
+
+// Clean up after each test
+afterEach(() => {
+  document.body.innerHTML = '';
+  vi.clearAllMocks();
+  vi.clearAllTimers();
+});
+
+// Polyfill for Custom Elements if needed
+if (!globalThis.customElements) {
+  class CustomElementRegistry {
+    private readonly definitions = new Map<string, CustomElementConstructor>();
+
+    define(name: string, constructor: CustomElementConstructor) {
+      this.definitions.set(name, constructor);
+    }
+
+    get(name: string) {
+      return this.definitions.get(name);
+    }
+
+    whenDefined(name: string): Promise<CustomElementConstructor> {
+      return Promise.resolve(this.definitions.get(name)!);
+    }
+
+    upgrade(_root: Node) {
+      // No-op for testing
+    }
+  }
+
+  // @ts-expect-error - Polyfill for testing
+  globalThis.customElements = new CustomElementRegistry();
+}
+
+// Mock requestAnimationFrame for testing
+globalThis.requestAnimationFrame = (callback: FrameRequestCallback) => {
+  return setTimeout(callback, 0) as unknown as number;
+};
+
+globalThis.cancelAnimationFrame = (id: number) => {
+  clearTimeout(id);
+};
+
+// Helper to wait for custom element to be defined
+export async function waitForElement(element: HTMLElement): Promise<void> {
+  return new Promise((resolve) => {
+    if (element.shadowRoot) {
+      resolve();
+    } else {
+      setTimeout(resolve, 0);
+    }
+  });
+}
+
+// Helper to wait for async operations
+export function waitForNextTick(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+// Helper to wait for multiple ticks
+export function waitForTicks(count: number): Promise<void> {
+  return new Promise((resolve) => {
+    let ticks = 0;
+    const tick = () => {
+      ticks++;
+      if (ticks >= count) {
+        resolve();
+      } else {
+        setTimeout(tick, 0);
+      }
+    };
+    tick();
+  });
+}

package/src/core/base/AIControl.ts

@@ -0,0 +1,230 @@
+import type { AIControlConfig, ThemeConfig } from './types';
+
+/**
+ * Base class for all AI Progress Controls
+ * Provides common functionality for Web Components including:
+ * - Theme management
+ * - Event handling
+ * - Accessibility features
+ * - Debug logging
+ *
+ * @example
+ * ```typescript
+ * class MyControl extends AIControl {
+ *   constructor() {
+ *     super();
+ *     this.attachShadow({ mode: 'open' });
+ *   }
+ *
+ *   protected render() {
+ *     // Your rendering logic
+ *   }
+ * }
+ * ```
+ */
+export abstract class AIControl extends HTMLElement {
+  protected config: AIControlConfig;
+  protected _disabled: boolean = false;
+  protected startTime: number = 0;
+
+  constructor(config: AIControlConfig = {}) {
+    super();
+    this.config = {
+      debug: false,
+      disabled: false,
+      ...config,
+    };
+    this._disabled = this.config.disabled ?? false;
+  }
+
+  /**
+   * Called when the element is connected to the DOM
+   */
+  connectedCallback(): void {
+    this.log('Component connected to DOM');
+    this.applyTheme();
+    this.setupAccessibility();
+    this.render();
+  }
+
+  /**
+   * Called when the element is disconnected from the DOM
+   */
+  disconnectedCallback(): void {
+    this.log('Component disconnected from DOM');
+    this.cleanup();
+  }
+
+  /**
+   * Called when an observed attribute changes
+   */
+  attributeChangedCallback(name: string, oldValue: string, newValue: string): void {
+    this.log(`Attribute ${name} changed from ${oldValue} to ${newValue}`);
+    this.handleAttributeChange(name, oldValue, newValue);
+  }
+
+  /**
+   * Apply theme using CSS custom properties
+   */
+  protected applyTheme(theme?: ThemeConfig): void {
+    if (!theme) return;
+
+    const root = this.shadowRoot?.host as HTMLElement;
+    if (!root) return;
+
+    Object.entries(theme).forEach(([key, value]) => {
+      const cssVarName = `--ai-${key.replaceAll(/([A-Z])/g, '-$1').toLowerCase()}`;
+      root.style.setProperty(cssVarName, value);
+    });
+  }
+
+  /**
+   * Set up accessibility features (ARIA attributes, keyboard navigation)
+   */
+  protected setupAccessibility(): void {
+    // Set role if not already set
+    if (!this.getAttribute('role')) {
+      this.setAttribute('role', this.getDefaultRole());
+    }
+
+    // Set aria-label if configured
+    if (this.config.ariaLabel) {
+      this.setAttribute('aria-label', this.config.ariaLabel);
+    }
+
+    // Set disabled state
+    if (this._disabled) {
+      this.setAttribute('aria-disabled', 'true');
+    }
+  }
+
+  /**
+   * Emit a custom event
+   */
+  protected emit<T>(eventName: string, detail?: T): void {
+    const event = new CustomEvent(eventName, {
+      detail,
+      bubbles: true,
+      composed: true,
+    });
+    this.dispatchEvent(event);
+    this.log(`Event emitted: ${eventName}`, detail);
+  }
+
+  /**
+   * Log debug messages (only if debug mode is enabled)
+   */
+  protected log(message: string, ...args: unknown[]): void {
+    if (this.config.debug) {
+      console.log(`[${this.constructor.name}] ${message}`, ...args);
+    }
+  }
+
+  /**
+   * Log errors (always logged)
+   */
+  protected logError(message: string, error?: Error): void {
+    console.error(`[${this.constructor.name}] ERROR: ${message}`, error);
+  }
+
+  /**
+   * Start timing an operation
+   */
+  protected startTimer(): void {
+    this.startTime = Date.now();
+  }
+
+  /**
+   * Get elapsed time since timer started
+   */
+  protected getElapsedTime(): number {
+    return Date.now() - this.startTime;
+  }
+
+  /**
+   * Format numbers for display (e.g., 1234 -> "1.2K")
+   */
+  protected formatNumber(num: number): string {
+    if (num >= 1_000_000) {
+      return `${(num / 1_000_000).toFixed(1)}M`;
+    }
+    if (num >= 1_000) {
+      return `${(num / 1_000).toFixed(1)}K`;
+    }
+    return num.toString();
+  }
+
+  /**
+   * Format duration in milliseconds to human-readable string
+   */
+  protected formatDuration(ms: number): string {
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+
+    if (hours > 0) {
+      return `${hours}h ${minutes % 60}m`;
+    }
+    if (minutes > 0) {
+      return `${minutes}m ${seconds % 60}s`;
+    }
+    return `${seconds}s`;
+  }
+
+  /**
+   * Calculate percentage safely
+   */
+  protected calculatePercentage(current: number, total: number): number {
+    if (total === 0) return 0;
+    return Math.min(100, Math.max(0, (current / total) * 100));
+  }
+
+  /**
+   * Get/Set disabled state
+   */
+  get disabled(): boolean {
+    return this._disabled;
+  }
+
+  set disabled(value: boolean) {
+    this._disabled = value;
+    if (value) {
+      this.setAttribute('aria-disabled', 'true');
+      this.setAttribute('disabled', '');
+    } else {
+      this.setAttribute('aria-disabled', 'false');
+      this.removeAttribute('disabled');
+    }
+    this.render();
+  }
+
+  /**
+   * Abstract method to render the component
+   * Must be implemented by subclasses
+   */
+  protected abstract render(): void;
+
+  /**
+   * Get the default ARIA role for this component
+   * Can be overridden by subclasses
+   */
+  protected getDefaultRole(): string {
+    return 'region';
+  }
+
+  /**
+   * Handle attribute changes
+   * Can be overridden by subclasses to handle specific attributes
+   */
+  protected handleAttributeChange(_name: string, _oldValue: string, _newValue: string): void {
+    // Override in subclasses
+  }
+
+  /**
+   * Cleanup resources when component is destroyed
+   * Can be overridden by subclasses
+   */
+  protected cleanup(): void {
+    // Override in subclasses
+  }
+}

package/src/core/base/index.ts

@@ -0,0 +1,3 @@
+export * from './AIControl';
+export * from './types';
+export * from './utils';

package/src/core/base/types.ts

@@ -0,0 +1,77 @@
+/**
+ * Size variant for components
+ */
+export type SizeVariant = 'compact' | 'default' | 'large';
+
+/**
+ * Visual style variant for components
+ */
+export type VisualVariant = 'default' | 'minimal' | 'gradient' | 'glassmorphic';
+
+/**
+ * Animation effect for progress indicators
+ */
+export type AnimationEffect = 'none' | 'striped' | 'pulse' | 'glow';
+
+/**
+ * Base configuration for all AI Progress Controls
+ */
+export interface AIControlConfig {
+  /** Enable/disable console logging for debugging */
+  debug?: boolean;
+  /** Custom CSS class names to apply */
+  className?: string;
+  /** Whether the control is disabled */
+  disabled?: boolean;
+  /** ARIA label for accessibility */
+  ariaLabel?: string;
+  /** Enable automatic cursor feedback based on state (default: true) */
+  cursorFeedback?: boolean;
+  /** Size variant: compact, default, or large */
+  size?: SizeVariant;
+  /** Visual style variant: default, minimal, gradient, or glassmorphic */
+  variant?: VisualVariant;
+  /** Animation effect: none, striped, pulse, or glow */
+  animation?: AnimationEffect;
+}
+
+/**
+ * Theme configuration using CSS custom properties
+ */
+export interface ThemeConfig {
+  primaryColor?: string;
+  secondaryColor?: string;
+  backgroundColor?: string;
+  textColor?: string;
+  borderRadius?: string;
+  fontSize?: string;
+  fontFamily?: string;
+}
+
+/**
+ * Event detail for progress updates
+ */
+export interface ProgressUpdateEvent {
+  current: number;
+  total?: number;
+  percentage?: number;
+  message?: string;
+}
+
+/**
+ * Event detail for errors
+ */
+export interface ErrorEvent {
+  message: string;
+  code?: string;
+  timestamp: number;
+}
+
+/**
+ * Event detail for completion
+ */
+export interface CompleteEvent {
+  duration: number;
+  timestamp: number;
+  metadata?: Record<string, unknown>;
+}

package/src/core/base/utils.ts

@@ -0,0 +1,168 @@
+/**
+ * Utility functions for AI Progress Controls
+ */
+
+/**
+ * Debounce function calls
+ */
+export function debounce<T extends (...args: any[]) => any>(
+  func: T,
+  wait: number
+): (...args: Parameters<T>) => void {
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+
+  return function (this: any, ...args: Parameters<T>) {
+    if (timeout) clearTimeout(timeout);
+    timeout = setTimeout(() => func.apply(this, args), wait);
+  };
+}
+
+/**
+ * Throttle function calls
+ */
+export function throttle<T extends (...args: any[]) => any>(
+  func: T,
+  limit: number
+): (...args: Parameters<T>) => void {
+  let inThrottle: boolean;
+  return function (this: any, ...args: Parameters<T>) {
+    if (!inThrottle) {
+      func.apply(this, args);
+      inThrottle = true;
+      setTimeout(() => (inThrottle = false), limit);
+    }
+  };
+}
+
+/**
+ * Clamp a number between min and max
+ */
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+/**
+ * Linear interpolation
+ */
+export function lerp(start: number, end: number, t: number): number {
+  return start + (end - start) * t;
+}
+
+/**
+ * Easing function for smooth animations
+ */
+export function easeOutCubic(t: number): number {
+  return 1 - Math.pow(1 - t, 3);
+}
+
+/**
+ * Generate a unique ID
+ */
+export function generateId(prefix: string = 'ai-control'): string {
+  return `${prefix}-${Math.random().toString(36).slice(2, 11)}`;
+}
+
+/**
+ * Check if reduced motion is preferred
+ */
+export function prefersReducedMotion(): boolean {
+  return globalThis.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+/**
+ * Format bytes to human-readable string
+ */
+export function formatBytes(bytes: number, decimals: number = 2): string {
+  if (bytes === 0) return '0 Bytes';
+
+  const k = 1024;
+  const dm = Math.max(0, decimals);
+  const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB'];
+
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+  return `${Number.parseFloat((bytes / Math.pow(k, i)).toFixed(dm))} ${sizes[i]}`;
+}
+
+/**
+ * Format currency (USD)
+ */
+export function formatCurrency(amount: number, decimals: number = 4): string {
+  return `$${amount.toFixed(decimals)}`;
+}
+
+/**
+ * Format seconds to human-readable time string
+ */
+export function formatTime(seconds: number): string {
+  if (seconds < 60) {
+    return `${Math.round(seconds)}s`;
+  }
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = Math.round(seconds % 60);
+  if (minutes < 60) {
+    return remainingSeconds > 0 ? `${minutes}m ${remainingSeconds}s` : `${minutes}m`;
+  }
+  const hours = Math.floor(minutes / 60);
+  const remainingMinutes = minutes % 60;
+  return remainingMinutes > 0 ? `${hours}h ${remainingMinutes}m` : `${hours}h`;
+}
+
+/**
+ * Calculate estimated time remaining
+ */
+export function calculateETA(current: number, total: number, startTime: number): number {
+  if (current === 0) return 0;
+
+  const elapsed = Date.now() - startTime;
+  const rate = current / elapsed;
+  const remaining = total - current;
+
+  return remaining / rate;
+}
+
+/**
+ * Parse CSS color to RGB
+ */
+export function parseColor(color: string): { r: number; g: number; b: number } | null {
+  const div = document.createElement('div');
+  div.style.color = color;
+  document.body.appendChild(div);
+
+  const computedColor = getComputedStyle(div).color;
+  div.remove();
+
+  const regex = /^rgb\((\d+),\s*(\d+),\s*(\d+)\)$/;
+  const match = regex.exec(computedColor);
+  if (match?.[1] && match?.[2] && match?.[3]) {
+    return {
+      r: Number.parseInt(match[1], 10),
+      g: Number.parseInt(match[2], 10),
+      b: Number.parseInt(match[3], 10),
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Create a style element with CSS
+ */
+export function createStyle(css: string): HTMLStyleElement {
+  const style = document.createElement('style');
+  style.textContent = css;
+  return style;
+}
+
+/**
+ * Check if an element is in viewport
+ */
+export function isInViewport(element: HTMLElement): boolean {
+  const rect = element.getBoundingClientRect();
+  return (
+    rect.top >= 0 &&
+    rect.left >= 0 &&
+    rect.bottom <= (globalThis.innerHeight || document.documentElement.clientHeight) &&
+    rect.right <= (globalThis.innerWidth || document.documentElement.clientWidth)
+  );
+}