allen-react-framework/README.md

A comprehensive eLearning framework for React applications

# Allen React Framework

A modern, accessible, and responsive eLearning framework built with React, TypeScript, and Tailwind CSS.

## 🚀 Features

- **Modern Architecture**: Built with React 18, TypeScript, and modern ES6+ features
- **Professional UI/UX**: Beautiful, responsive design with Tailwind CSS
- **Accessibility First**: WCAG compliant with proper ARIA labels and keyboard navigation
- **Component-Based**: Extensible interaction system with a base class architecture
- **Responsive Design**: Mobile-first approach with progressive enhancement
- **Type Safety**: Full TypeScript support with comprehensive type definitions

## 🏗️ Architecture

### Core Components

- **BaseInteraction**: Abstract base class for all interactions
- **MultipleChoiceInteraction**: Full-featured multiple choice with scoring and feedback
- **DragDropInteraction**: Interactive drag & drop categorization
- **TextEntryInteraction**: Text input with validation and similarity scoring
- **SimpleInteraction**: Example implementation showing the framework's capabilities
- **Type System**: Comprehensive TypeScript interfaces for configuration and state

### Key Features

- **State Management**: Built-in state handling with lifecycle hooks
- **Event System**: Standardized event handling for state changes and completion
- **Styling System**: Tailwind CSS with custom component classes
- **Responsive Utilities**: Mobile-first responsive design utilities

## 🛠️ Technology Stack

- **Frontend**: React 18 + TypeScript
- **Styling**: Tailwind CSS v4 + PostCSS
- **Build Tool**: Webpack 5 + ts-loader
- **Development**: Hot reload with webpack-dev-server

## 📦 Installation

```bash
# Clone the repository
git clone <your-repo-url>
cd allen-react-framework

# Install dependencies
npm install

# Start development server
npm start

# Build for production
npm run build
```

## 🎯 Usage

### Basic Interaction Setup

```typescript
import { SimpleInteraction } from './interactions/SimpleInteraction';

const config = {
  id: 'demo-1',
  type: 'simple-question',
  title: 'Demo Question',
  description: 'This is a simple demonstration',
  question: 'What is the capital of France?',
  correctAnswer: 'Paris'
};

<SimpleInteraction
  config={config}
  onStateChange={(state) => console.log('State:', state)}
  onComplete={(result) => console.log('Result:', result)}
/>
```

### Using Built-in Interactions

```typescript
import { MultipleChoiceInteraction } from './interactions/MultipleChoiceInteraction';
import { DragDropInteraction } from './interactions/DragDropInteraction';
import { TextEntryInteraction } from './interactions/TextEntryInteraction';

// Multiple Choice
const mcConfig = {
  id: 'question-1',
  type: 'multiple-choice',
  title: 'Knowledge Check',
  question: 'What is the capital of France?',
  options: [
    { id: '1', text: 'Paris', isCorrect: true },
    { id: '2', text: 'London', isCorrect: false },
    { id: '3', text: 'Berlin', isCorrect: false }
  ],
  scoring: { pointsPerCorrect: 10, pointsPerIncorrect: 0 }
};

<MultipleChoiceInteraction
  config={mcConfig}
  onComplete={(result) => console.log('Score:', result.score)}
/>

// Drag & Drop
const ddConfig = {
  id: 'categorize-1',
  type: 'drag-drop',
  instruction: 'Categorize these items',
  dragItems: [
    { id: '1', content: 'JavaScript', type: 'language' },
    { id: '2', content: 'React', type: 'framework' }
  ],
  dropZones: [
    { id: 'languages', title: 'Languages', accepts: ['language'] },
    { id: 'frameworks', title: 'Frameworks', accepts: ['framework'] }
  ]
};

<DragDropInteraction
  config={ddConfig}
  onComplete={(result) => console.log('Result:', result)}
/>

// Text Entry
const teConfig = {
  id: 'text-1',
  type: 'text-entry',
  question: 'What is your favorite programming language?',
  correctAnswers: ['JavaScript', 'Python', 'TypeScript'],
  allowPartialMatch: true,
  validation: { minLength: 3, maxLength: 20 }
};

<TextEntryInteraction
  config={teConfig}
  onComplete={(result) => console.log('Answer:', result.data.userAnswer)}
/>
```

### Creating Custom Interactions

```typescript
import { BaseInteraction } from './core/BaseInteraction';

export class CustomInteraction extends BaseInteraction {
  renderContent(): React.ReactNode {
    // Your custom content here
    return <div>Custom Content</div>;
  }

  renderFooter(): React.ReactNode {
    // Your custom footer here
    return <div>Custom Footer</div>;
  }
}
```

## 🎨 Styling

The framework uses Tailwind CSS with custom component classes:

- **`.interaction-container`**: Main interaction wrapper
- **`.btn`**: Base button styles
- **`.btn-primary`**: Primary button variant
- **`.btn-success`**: Success button variant
- **`.btn-secondary`**: Secondary button variant
- **`.form-input`**: Form input styling
- **`.form-label`**: Form label styling

## ♿ Accessibility

- **ARIA Labels**: Proper labeling for screen readers
- **Keyboard Navigation**: Full keyboard support
- **Focus Management**: Clear focus indicators
- **Semantic HTML**: Proper heading hierarchy and landmarks
- **High Contrast**: WCAG AA compliant color combinations

## 📱 Responsive Design

- **Mobile First**: Designed for mobile devices first
- **Breakpoints**: Responsive utilities for sm:, md:, lg:, xl:
- **Touch Friendly**: Minimum 44px touch targets
- **Flexible Layouts**: Grid and flexbox based responsive layouts

## 🔧 Development

### Project Structure

```
src/
├── core/           # Base classes and utilities
├── interactions/   # Interaction implementations
├── types/          # TypeScript type definitions
├── styles/         # CSS and Tailwind configuration
└── index.tsx       # Main application entry point
```

### Available Scripts

- `npm start`: Start development server
- `npm run build`: Build for production
- `npm run test`: Run tests (when implemented)

## 🚀 Roadmap

### Phase 1: Foundation ✅
- [x] BaseInteraction class
- [x] Tailwind CSS integration
- [x] Basic interaction types
- [x] Accessibility features

### Phase 2: Enhanced Interactions
- [ ] Multiple choice interactions
- [ ] Drag and drop interactions
- [ ] Form-based interactions
- [ ] Assessment flows

### Phase 3: Advanced Features
- [ ] XState integration for complex state
- [ ] Animation system
- [ ] Analytics and tracking
- [ ] Performance optimizations

### Phase 4: Production Ready
- [ ] Testing suite
- [ ] Documentation
- [ ] Performance monitoring
- [ ] Deployment tools

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 📄 License

MIT License - see LICENSE file for details

## 🏢 About

Built by Allen Interactions for creating engaging, accessible eLearning experiences.

---

**Version**: 0.1.0  
**Last Updated**: August 2025  
**Status**: Foundation Complete - Ready for Enhancement