@sc4rfurryx/proteusjs 1.0.0

package/API.md

@@ -0,0 +1,438 @@
+# ProteusJS API Documentation
+
+## 🚀 Getting Started
+
+### Installation & Initialization
+
+```typescript
+import { ProteusJS } from '@sc4rfurryx/proteusjs';
+
+// Initialize ProteusJS
+const proteus = new ProteusJS(options?);
+```
+
+### Constructor Options
+
+```typescript
+interface ProteusOptions {
+  performance?: {
+    debounceMs?: number;        // Default: 16ms
+    enableCaching?: boolean;    // Default: true
+    memoryLimit?: number;       // Default: 100MB
+  };
+  accessibility?: {
+    defaultLevel?: 'A' | 'AA' | 'AAA';  // Default: 'AA'
+    announcements?: boolean;    // Default: true
+  };
+  debug?: boolean;             // Default: false
+}
+```
+
+## 📦 Container Query API
+
+### `container(selector, options)`
+
+Creates responsive containers with element-based breakpoints.
+
+```typescript
+proteus.container(selector: string | Element | Element[], options: ContainerOptions)
+
+interface ContainerOptions {
+  breakpoints: BreakpointConfig;
+  containerType?: 'inline-size' | 'size' | 'block-size' | 'auto';
+  debounceMs?: number;
+  announceChanges?: boolean;
+  cssClasses?: boolean;
+  callbacks?: {
+    resize?: (state: ContainerState) => void;
+    breakpointChange?: (breakpoint: string, active: boolean) => void;
+  };
+}
+
+interface BreakpointConfig {
+  [name: string]: string;  // e.g., { sm: '300px', md: '600px' }
+}
+
+interface ContainerState {
+  width: number;
+  height: number;
+  activeBreakpoints: string[];
+  containerType: string;
+}
+```
+
+#### Example Usage
+
+```typescript
+// Basic container with breakpoints
+proteus.container('.sidebar', {
+  breakpoints: {
+    sm: '200px',
+    md: '400px',
+    lg: '600px'
+  }
+});
+
+// Advanced container with callbacks
+proteus.container('.product-grid', {
+  breakpoints: { sm: '300px', lg: '900px' },
+  announceChanges: true,
+  callbacks: {
+    breakpointChange: (breakpoint, active) => {
+      console.log(`${breakpoint} is now ${active ? 'active' : 'inactive'}`);
+    }
+  }
+});
+```
+
+## 📝 Typography API
+
+### `fluidType(selector, options)`
+
+Applies fluid typography with accessibility compliance.
+
+```typescript
+proteus.fluidType(selector: string | Element | Element[], options: FluidTypeOptions)
+
+interface FluidTypeOptions {
+  minSize: number;              // Minimum font size in specified unit
+  maxSize: number;              // Maximum font size in specified unit
+  minContainer?: number;        // Minimum container width (default: 320)
+  maxContainer?: number;        // Maximum container width (default: 1200)
+  unit?: 'px' | 'rem' | 'em';   // Default: 'px'
+  accessibility?: 'A' | 'AA' | 'AAA';  // WCAG compliance level
+  scalingFunction?: 'linear' | 'exponential' | string;
+}
+```
+
+#### Example Usage
+
+```typescript
+// Basic fluid typography
+proteus.fluidType('h1', {
+  minSize: 24,
+  maxSize: 48
+});
+
+// AAA accessibility compliance
+proteus.fluidType('p', {
+  minSize: 16,
+  maxSize: 18,
+  accessibility: 'AAA',  // Enforces 1.5+ line height
+  unit: 'rem'
+});
+
+// Custom scaling
+proteus.fluidType('.hero-title', {
+  minSize: 32,
+  maxSize: 72,
+  minContainer: 400,
+  maxContainer: 1400,
+  scalingFunction: 'exponential'
+});
+```
+
+## ♿ Accessibility API
+
+### `enableAccessibility(element, options)`
+
+Enables comprehensive accessibility features.
+
+```typescript
+proteus.enableAccessibility(element: Element, options: AccessibilityOptions)
+
+interface AccessibilityOptions {
+  wcagLevel?: 'A' | 'AA' | 'AAA';
+  screenReader?: boolean;
+  keyboardNavigation?: boolean;
+  motionPreferences?: boolean;
+  colorCompliance?: boolean;
+  cognitiveAccessibility?: boolean;
+  announcements?: boolean;
+  focusManagement?: boolean;
+  skipLinks?: boolean;
+  landmarks?: boolean;
+  autoLabeling?: boolean;
+  enhanceErrorMessages?: boolean;
+  showReadingTime?: boolean;
+  simplifyContent?: boolean;
+  readingLevel?: 'elementary' | 'middle' | 'high' | 'college';
+}
+```
+
+#### Example Usage
+
+```typescript
+// Basic accessibility enhancement
+proteus.enableAccessibility(document.body, {
+  wcagLevel: 'AA',
+  screenReader: true,
+  keyboardNavigation: true
+});
+
+// Cognitive accessibility features
+proteus.enableAccessibility(document.main, {
+  wcagLevel: 'AAA',
+  cognitiveAccessibility: true,
+  showReadingTime: true,
+  simplifyContent: true,
+  readingLevel: 'middle'
+});
+
+// Form accessibility enhancement
+proteus.enableAccessibility(document.querySelector('form'), {
+  enhanceErrorMessages: true,
+  autoLabeling: true,
+  focusManagement: true
+});
+```
+
+### `auditAccessibility(element)`
+
+Performs comprehensive accessibility audit.
+
+```typescript
+proteus.auditAccessibility(element: Element): AccessibilityReport
+
+interface AccessibilityReport {
+  score: number;                // 0-100
+  level: 'A' | 'AA' | 'AAA';
+  passed: boolean;
+  issues: AccessibilityIssue[];
+  recommendations: string[];
+}
+
+interface AccessibilityIssue {
+  type: string;
+  severity: 'error' | 'warning' | 'info';
+  element: Element;
+  description: string;
+  wcagReference: string;
+}
+```
+
+## 🎨 Layout API
+
+### `createGrid(selector, options)`
+
+Creates adaptive CSS Grid layouts.
+
+```typescript
+proteus.createGrid(selector: string | Element | Element[], options: GridOptions)
+
+interface GridOptions {
+  minItemWidth: string;         // e.g., '250px'
+  gap?: string;                 // Default: '1rem'
+  maxColumns?: number;          // Maximum columns
+  aspectRatio?: string;         // e.g., '16/9'
+  responsive?: boolean;         // Default: true
+}
+```
+
+#### Example Usage
+
+```typescript
+// Basic responsive grid
+proteus.createGrid('.gallery', {
+  minItemWidth: '200px',
+  gap: '1rem'
+});
+
+// Advanced grid with constraints
+proteus.createGrid('.product-grid', {
+  minItemWidth: '250px',
+  maxColumns: 4,
+  aspectRatio: '4/3',
+  gap: '2rem'
+});
+```
+
+### `applySpacing(element, options)`
+
+Applies consistent spacing with vertical rhythm.
+
+```typescript
+proteus.applySpacing(element: Element, options: SpacingOptions)
+
+interface SpacingOptions {
+  baseSize: number;             // Base font size in px
+  scale: number;                // Spacing scale ratio
+  rhythm?: boolean;             // Enable vertical rhythm
+  unit?: 'px' | 'rem' | 'em';
+}
+```
+
+## 🚀 Performance API
+
+### `getPerformanceMetrics()`
+
+Returns detailed performance information.
+
+```typescript
+proteus.getPerformanceMetrics(): PerformanceMetrics
+
+interface PerformanceMetrics {
+  renderTime: number;           // Average render time in ms
+  memoryUsage: number;          // Memory usage in MB
+  cacheHitRate: number;         // Cache efficiency (0-1)
+  activeElements: number;       // Number of managed elements
+  lastUpdateTime: number;       // Timestamp of last update
+  fps: number;                  // Current frame rate
+}
+```
+
+### `enablePerformanceMonitoring(options)`
+
+Enables real-time performance monitoring.
+
+```typescript
+proteus.enablePerformanceMonitoring(options: PerformanceOptions)
+
+interface PerformanceOptions {
+  interval?: number;            // Monitoring interval in ms
+  threshold?: {
+    renderTime?: number;        // Alert threshold for render time
+    memoryUsage?: number;       // Alert threshold for memory usage
+    fps?: number;               // Alert threshold for FPS
+  };
+  onAlert?: (metric: string, value: number) => void;
+}
+```
+
+## 🔧 Utility Methods
+
+### `destroy()`
+
+Cleans up all ProteusJS instances and event listeners.
+
+```typescript
+proteus.destroy(): void
+```
+
+### `getVersion()`
+
+Returns the current ProteusJS version.
+
+```typescript
+proteus.getVersion(): string
+```
+
+### `isSupported(feature)`
+
+Checks if a feature is supported in the current browser.
+
+```typescript
+proteus.isSupported(feature: string): boolean
+
+// Supported features:
+// 'container-queries', 'resize-observer', 'intersection-observer'
+```
+
+## 🎯 Advanced Features
+
+### `autoOptimize(element, options)`
+
+Automatically applies optimal settings based on content analysis.
+
+```typescript
+proteus.autoOptimize(element: Element, options: AutoOptimizeOptions)
+
+interface AutoOptimizeOptions {
+  typography?: boolean | FluidTypeOptions;
+  accessibility?: boolean | AccessibilityOptions;
+  container?: boolean | ContainerOptions;
+  performance?: boolean | PerformanceOptions;
+}
+```
+
+#### Example Usage
+
+```typescript
+// Automatic optimization with defaults
+proteus.autoOptimize(document.body);
+
+// Custom optimization settings
+proteus.autoOptimize(document.body, {
+  typography: { accessibility: 'AAA' },
+  accessibility: { wcagLevel: 'AA' },
+  container: { breakpoints: { sm: '300px', lg: '800px' } }
+});
+```
+
+## 🔌 Framework Integration
+
+### React Hooks
+
+```typescript
+import { useProteusContainer, useFluidType, useAccessibility } from '@sc4rfurryx/proteusjs/react';
+
+// Container hook
+const containerRef = useProteusContainer({
+  breakpoints: { sm: '300px', lg: '600px' }
+});
+
+// Typography hook
+const textRef = useFluidType({
+  minSize: 16,
+  maxSize: 24,
+  accessibility: 'AA'
+});
+
+// Accessibility hook
+const accessibleRef = useAccessibility({
+  wcagLevel: 'AA',
+  screenReader: true
+});
+```
+
+### Vue Composables
+
+```typescript
+import { useProteusContainer, useFluidType } from '@sc4rfurryx/proteusjs/vue';
+
+// In setup()
+const { containerRef } = useProteusContainer({
+  breakpoints: { sm: '300px', lg: '600px' }
+});
+
+const { textRef } = useFluidType({
+  minSize: 16,
+  maxSize: 24
+});
+```
+
+## 🐛 Error Handling
+
+### Error Types
+
+```typescript
+class ProteusError extends Error {
+  code: string;
+  element?: Element;
+  details?: any;
+}
+
+// Error codes:
+// 'INVALID_SELECTOR' - Invalid element selector
+// 'UNSUPPORTED_FEATURE' - Feature not supported in browser
+// 'INVALID_OPTIONS' - Invalid configuration options
+// 'PERFORMANCE_THRESHOLD' - Performance threshold exceeded
+```
+
+### Error Handling Example
+
+```typescript
+try {
+  proteus.container('.invalid-selector', {
+    breakpoints: { sm: '300px' }
+  });
+} catch (error) {
+  if (error instanceof ProteusError) {
+    console.error(`ProteusJS Error [${error.code}]:`, error.message);
+  }
+}
+```
+
+---
+
+**ProteusJS API Documentation** - Complete reference for all features and methods

package/FEATURES.md

@@ -0,0 +1,286 @@
+# ProteusJS Features Documentation
+
+## 🎯 Core Features Overview
+
+ProteusJS is a comprehensive web development framework that provides intelligent layout systems, advanced typography, WCAG-compliant accessibility features, and performance optimizations. This document details all implemented features and capabilities.
+
+## 🏗️ Architecture Overview
+
+### Core Components
+- **ProteusJS Core**: Main orchestration class
+- **Container Manager**: Handles responsive container queries
+- **Typography Engine**: Fluid typography and line height optimization
+- **Accessibility Engine**: WCAG compliance and screen reader support
+- **Performance Tracker**: Real-time monitoring and optimization
+- **Memory Manager**: Automatic cleanup and leak prevention
+
+## 📦 Container Query System
+
+### Smart Container Management
+- **Element-based breakpoints**: Responsive design based on container size, not viewport
+- **Real-time adaptation**: Automatic layout updates on container resize
+- **Memory-efficient observers**: Optimized ResizeObserver implementation
+- **CSS class injection**: Automatic breakpoint classes for styling
+
+### Container Features
+```typescript
+proteus.container('.sidebar', {
+  breakpoints: {
+    sm: '200px',
+    md: '400px', 
+    lg: '600px'
+  },
+  containerType: 'inline-size', // 'size' | 'block-size' | 'auto'
+  debounceMs: 16, // Performance optimization
+  announceChanges: true, // Screen reader announcements
+  callbacks: {
+    resize: (state) => { /* Handle resize */ },
+    breakpointChange: (breakpoint, active) => { /* Handle breakpoint change */ }
+  }
+});
+```
+
+### Performance Optimizations
+- **Debounced updates**: Prevents excessive recalculations
+- **Batch processing**: Groups multiple updates for efficiency
+- **Memory management**: Automatic cleanup of observers
+- **Caching**: Stores computed values to avoid recalculation
+
+## 📝 Typography System
+
+### Fluid Typography Engine
+- **Clamp-based scaling**: Modern CSS clamp() function for smooth scaling
+- **Accessibility compliance**: WCAG AA/AAA line height requirements
+- **Multi-unit support**: px, rem, em, and viewport units
+- **Custom scaling functions**: Linear, exponential, and custom curves
+
+### Typography Features
+```typescript
+proteus.fluidType('h1, h2, h3', {
+  minSize: 16,
+  maxSize: 32,
+  minContainer: 320,
+  maxContainer: 1200,
+  accessibility: 'AAA', // Enforces 1.5+ line height
+  unit: 'rem',
+  scalingFunction: 'linear'
+});
+```
+
+### Line Height Optimization
+- **Automatic optimization**: Calculates optimal line height for readability
+- **Accessibility enforcement**: Ensures WCAG compliance
+- **Multi-language support**: Adapts to different writing systems
+- **User preference detection**: Respects system accessibility settings
+
+## ♿ Accessibility Engine
+
+### WCAG Compliance Levels
+- **Level A**: Basic accessibility requirements
+- **Level AA**: Standard compliance for most applications
+- **Level AAA**: Enhanced accessibility for critical applications
+
+### Screen Reader Support
+- **Live regions**: Automatic announcements for dynamic content
+- **ARIA labeling**: Intelligent label generation and association
+- **Focus management**: Enhanced keyboard navigation
+- **Skip links**: Automatic navigation shortcuts
+
+### Cognitive Accessibility
+```typescript
+proteus.enableAccessibility(document.body, {
+  wcagLevel: 'AAA',
+  screenReader: true,
+  cognitiveAccessibility: true,
+  showReadingTime: true,
+  simplifyContent: true,
+  readingLevel: 'elementary', // 'middle' | 'high' | 'college'
+  enhanceErrorMessages: true
+});
+```
+
+### Accessibility Features
+- **Reading time estimates**: Automatic calculation and display
+- **Content simplification**: Toggle between original and simplified text
+- **Error message enhancement**: Links inputs to error descriptions
+- **Keyboard navigation**: Enhanced tab order and focus indicators
+- **Motion preferences**: Respects prefers-reduced-motion
+- **Color compliance**: Automatic contrast checking and adjustment
+
+## 🎨 Layout System
+
+### Adaptive Grid Layouts
+- **CSS Grid enhancement**: Intelligent grid systems that adapt to content
+- **Minimum item width**: Ensures content remains readable
+- **Automatic columns**: Calculates optimal column count
+- **Gap management**: Consistent spacing across breakpoints
+
+### Grid Features
+```typescript
+proteus.createGrid('.gallery', {
+  minItemWidth: '250px',
+  gap: '1rem',
+  maxColumns: 4,
+  aspectRatio: '16/9',
+  responsive: true
+});
+```
+
+### Spacing System
+- **Vertical rhythm**: Consistent spacing based on typography
+- **Scale-based spacing**: Harmonious spacing relationships
+- **Responsive spacing**: Adapts to container size
+- **Baseline grid**: Aligns elements to typographic baseline
+
+## 🚀 Performance System
+
+### Real-time Monitoring
+- **FPS tracking**: Monitors frame rate and performance
+- **Memory usage**: Tracks memory consumption and leaks
+- **Operation timing**: Measures execution time of operations
+- **Cache efficiency**: Monitors cache hit rates
+
+### Performance Features
+```typescript
+const metrics = proteus.getPerformanceMetrics();
+// Returns: { renderTime, memoryUsage, cacheHitRate, activeElements }
+```
+
+### Optimization Strategies
+- **Lazy loading**: Defers initialization until needed
+- **Intersection observers**: Efficient viewport detection
+- **Debounced events**: Prevents excessive calculations
+- **Memory cleanup**: Automatic garbage collection
+- **Batch updates**: Groups DOM modifications
+
+## 🔧 Integration System
+
+### Framework Support
+- **React**: Hooks and components for seamless integration
+- **Vue 3**: Composables and directives
+- **Angular**: Services and directives
+- **Vanilla JS**: Direct API access
+
+### React Integration
+```tsx
+import { useProteusContainer } from 'proteusjs/react';
+
+function ResponsiveComponent() {
+  const containerRef = useProteusContainer({
+    breakpoints: { sm: '300px', lg: '600px' }
+  });
+  
+  return <div ref={containerRef}>Responsive content</div>;
+}
+```
+
+### Vue Integration
+```vue
+<template>
+  <div v-proteus-container="{ breakpoints: { sm: '300px', lg: '600px' } }">
+    Responsive content
+  </div>
+</template>
+```
+
+## 🧪 Testing & Validation
+
+### Comprehensive Test Suite
+- **Unit tests**: 95%+ code coverage
+- **Integration tests**: End-to-end functionality
+- **Accessibility tests**: WCAG compliance validation
+- **Performance tests**: Benchmarks and load testing
+- **Cross-browser tests**: Automated compatibility testing
+
+### Accessibility Validation
+```typescript
+const report = proteus.auditAccessibility(document.body);
+// Returns detailed accessibility report with issues and recommendations
+```
+
+### Performance Benchmarks
+- **Initialization time**: < 50ms for typical applications
+- **Update performance**: < 16ms for smooth 60fps
+- **Memory efficiency**: < 5MB for large applications
+- **Bundle size**: < 50KB gzipped
+
+## 🌐 Browser Compatibility
+
+### Modern Browser Support
+- **Chrome/Edge**: 88+ (full support)
+- **Firefox**: 85+ (full support)
+- **Safari**: 14+ (full support)
+- **iOS Safari**: 14+ (full support)
+- **Android Chrome**: 88+ (full support)
+
+### Polyfills & Fallbacks
+- **Container Query polyfill**: For older browsers
+- **ResizeObserver polyfill**: Universal resize detection
+- **IntersectionObserver polyfill**: Viewport detection
+- **Graceful degradation**: Fallback strategies for unsupported features
+
+## 🔒 Security & Privacy
+
+### Security Features
+- **CSP compliance**: Content Security Policy compatible
+- **XSS protection**: Input sanitization and validation
+- **No external dependencies**: Self-contained library
+- **Privacy-first**: No data collection or tracking
+
+## 📊 Production Readiness
+
+### Quality Assurance
+- **TypeScript strict mode**: Type safety and error prevention
+- **ESLint + Prettier**: Code quality and consistency
+- **Automated testing**: Continuous integration and testing
+- **Performance monitoring**: Real-time metrics and alerting
+
+### Deployment Features
+- **Tree shaking**: Only include used features
+- **Minification**: Optimized production builds
+- **Source maps**: Debugging support
+- **CDN ready**: Optimized for content delivery networks
+
+## 🎯 Use Cases & Applications
+
+### E-commerce Platforms
+- Responsive product grids
+- Accessible checkout flows
+- Performance-optimized catalogs
+- Mobile-first design
+
+### Content Management Systems
+- Fluid typography for articles
+- Accessible content editing
+- Responsive media galleries
+- SEO-optimized layouts
+
+### Dashboard Applications
+- Adaptive data visualization
+- Accessible form controls
+- Real-time performance monitoring
+- Responsive navigation systems
+
+### Educational Platforms
+- Cognitive accessibility features
+- Reading time estimates
+- Content simplification
+- Multi-language support
+
+## 🔮 Future Roadmap
+
+### Planned Features
+- **Advanced animations**: FLIP-based transitions
+- **Theme system**: Intelligent dark mode and theming
+- **Micro-interactions**: Enhanced user experience
+- **AI-powered optimization**: Automatic performance tuning
+
+### Community Features
+- **Plugin system**: Extensible architecture
+- **Community themes**: Shared design systems
+- **Integration templates**: Framework-specific starters
+- **Performance analytics**: Detailed insights and recommendations
+
+---
+
+**ProteusJS** - Comprehensive web development framework for the modern web