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

# 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

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

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

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