275 lines
8.3 KiB
Markdown
275 lines
8.3 KiB
Markdown
# Progressive Multi-Step Instruction System Plan
|
|
|
|
## Overview
|
|
|
|
Implement a comprehensive system that coordinates multi-step instructions, bead highlighting, and directional movement indicators to create a step-by-step progressive tutorial experience.
|
|
|
|
## Current System Analysis
|
|
|
|
### 1. Bead Highlighting System
|
|
|
|
- **Location**: `packages/abacus-react/src/AbacusReact.tsx`
|
|
- **Interface**: `BeadHighlight` (union of PlaceValueBead | ColumnIndexBead)
|
|
- **Current functionality**: Static highlighting of beads
|
|
- **Limitation**: Shows all highlighted beads at once, no progressive revelation
|
|
|
|
### 2. Multi-Step Instructions
|
|
|
|
- **Location**: `apps/web/src/utils/abacusInstructionGenerator.ts`
|
|
- **Data**: `multiStepInstructions: string[]`
|
|
- **Current functionality**: Generates step-by-step text instructions
|
|
- **Example (99+1)**:
|
|
1. "Click earth bead 1 in the hundreds column to add it"
|
|
2. "Remove 9 from ones column (subtracting second part of decomposition)"
|
|
3. "Remove 90 from tens column (subtracting first part of decomposition)"
|
|
|
|
### 3. Progressive Display (GuidedAdditionTutorial)
|
|
|
|
- **Location**: `apps/web/src/components/GuidedAdditionTutorial.tsx`
|
|
- **State**: `multiStepProgress: number` (tracks current step)
|
|
- **Functionality**: Shows current step in bold, dims future steps
|
|
- **Limitation**: No coordination with bead highlighting
|
|
|
|
### 4. Bead Generation Logic
|
|
|
|
- **Location**: `apps/web/src/utils/abacusInstructionGenerator.ts:generateBeadHighlights()`
|
|
- **Current**: Generates all beads for entire operation
|
|
- **Limitation**: No step-by-step bead breakdown
|
|
|
|
## Proposed Solution Architecture
|
|
|
|
### Phase 1: Enhanced Data Structures
|
|
|
|
#### 1.1 Extended BeadHighlight Interface
|
|
|
|
```typescript
|
|
export interface StepBeadHighlight extends BeadHighlight {
|
|
stepIndex: number; // Which instruction step this bead belongs to
|
|
direction: "up" | "down" | "activate" | "deactivate"; // Movement direction
|
|
order?: number; // Order within the step (for multiple beads per step)
|
|
}
|
|
```
|
|
|
|
#### 1.2 Enhanced GeneratedInstruction Interface
|
|
|
|
```typescript
|
|
export interface GeneratedInstruction {
|
|
// ... existing fields
|
|
multiStepInstructions?: string[];
|
|
stepBeadHighlights?: StepBeadHighlight[]; // NEW: beads grouped by step
|
|
totalSteps?: number; // NEW: total number of steps
|
|
}
|
|
```
|
|
|
|
#### 1.3 Progressive Instruction State
|
|
|
|
```typescript
|
|
interface ProgressiveInstructionState {
|
|
currentStep: number;
|
|
totalSteps: number;
|
|
currentStepBeads: BeadHighlight[]; // Beads for current step only
|
|
completedStepBeads: BeadHighlight[]; // All beads from previous steps
|
|
currentStepInstruction: string;
|
|
}
|
|
```
|
|
|
|
### Phase 2: Enhanced Instruction Generation
|
|
|
|
#### 2.1 Modify generateEnhancedStepInstructions()
|
|
|
|
- Generate beads per step, not just text instructions
|
|
- Map each bead operation to its corresponding instruction step
|
|
- Determine movement direction for each bead
|
|
|
|
#### 2.2 New Function: generateStepBeadMapping()
|
|
|
|
```typescript
|
|
function generateStepBeadMapping(
|
|
startValue: number,
|
|
targetValue: number,
|
|
additions: BeadHighlight[],
|
|
removals: BeadHighlight[],
|
|
decomposition: any,
|
|
multiStepInstructions: string[],
|
|
): StepBeadHighlight[];
|
|
```
|
|
|
|
### Phase 3: AbacusReact Component Enhancements
|
|
|
|
#### 3.1 Add Directional Indicators
|
|
|
|
- **New Props**:
|
|
|
|
```typescript
|
|
interface AbacusReactProps {
|
|
// ... existing props
|
|
stepBeadHighlights?: StepBeadHighlight[];
|
|
showDirectionIndicators?: boolean;
|
|
}
|
|
```
|
|
|
|
- **Visual Implementation**:
|
|
- Arrow overlays on beads (↑ for up/activate, ↓ for down/deactivate)
|
|
- Different highlight colors for different directions
|
|
- Animation hints for movement direction
|
|
|
|
#### 3.2 Enhanced Bead Styling
|
|
|
|
```typescript
|
|
interface BeadDirectionStyle extends BeadStyle {
|
|
directionIndicator?: {
|
|
show: boolean;
|
|
direction: "up" | "down" | "activate" | "deactivate";
|
|
color?: string;
|
|
size?: number;
|
|
};
|
|
}
|
|
```
|
|
|
|
### Phase 4: TutorialPlayer Progressive Display
|
|
|
|
#### 4.1 Add Progressive State Management
|
|
|
|
```typescript
|
|
interface TutorialPlayerState {
|
|
// ... existing state
|
|
progressiveInstruction: ProgressiveInstructionState | null;
|
|
}
|
|
```
|
|
|
|
#### 4.2 Progressive Instruction Logic
|
|
|
|
- Track current step within multi-step instructions
|
|
- Update highlighted beads based on current step
|
|
- Show only current step instruction in bold
|
|
- Dim future steps, mark completed steps
|
|
|
|
#### 4.3 Step Advancement Logic
|
|
|
|
- User completes current step → advance to next step
|
|
- Update bead highlights to show next step's beads
|
|
- Maintain previously completed beads in "completed" state
|
|
|
|
### Phase 5: Testing Strategy
|
|
|
|
#### 5.1 Unit Tests for Step-by-Step Generation
|
|
|
|
```typescript
|
|
describe("Progressive Instruction Generation", () => {
|
|
test("99+1 generates correct step-bead mapping", () => {
|
|
const instruction = generateAbacusInstructions(99, 100);
|
|
expect(instruction.stepBeadHighlights).toHaveLength(3);
|
|
|
|
// Step 0: Add 1 to hundreds
|
|
expect(instruction.stepBeadHighlights[0]).toEqual({
|
|
stepIndex: 0,
|
|
placeValue: 2,
|
|
beadType: "earth",
|
|
position: 0,
|
|
direction: "activate",
|
|
});
|
|
|
|
// Step 1: Remove 9 from ones (heaven + 4 earth)
|
|
const step1Beads = instruction.stepBeadHighlights.filter(
|
|
(b) => b.stepIndex === 1,
|
|
);
|
|
expect(step1Beads).toHaveLength(5); // 1 heaven + 4 earth
|
|
|
|
// Step 2: Remove 90 from tens (heaven + 4 earth)
|
|
const step2Beads = instruction.stepBeadHighlights.filter(
|
|
(b) => b.stepIndex === 2,
|
|
);
|
|
expect(step2Beads).toHaveLength(5); // 1 heaven + 4 earth
|
|
});
|
|
|
|
test("3+98 generates correct step-bead mapping", () => {
|
|
// Test simpler complement case
|
|
});
|
|
});
|
|
```
|
|
|
|
#### 5.2 Integration Tests for Progressive Display
|
|
|
|
```typescript
|
|
describe("Progressive Tutorial Player", () => {
|
|
test("shows only current step beads", () => {
|
|
// Render tutorial player with 99+1 case
|
|
// Verify only step 0 beads are highlighted initially
|
|
// Advance step, verify step 1 beads appear
|
|
});
|
|
|
|
test("direction indicators display correctly", () => {
|
|
// Verify arrows/indicators show correct directions
|
|
});
|
|
});
|
|
```
|
|
|
|
#### 5.3 Visual Regression Tests
|
|
|
|
- Storybook stories for each progression state
|
|
- Visual comparisons for direction indicators
|
|
- Progressive highlighting behavior
|
|
|
|
## Implementation Plan
|
|
|
|
### Iteration 1: Data Structure Foundation
|
|
|
|
1. **Design and implement enhanced interfaces** ✓
|
|
2. **Modify instruction generator to produce step-bead mapping**
|
|
3. **Unit tests for step-bead generation**
|
|
4. **Validate with 99+1 and 3+98 test cases**
|
|
|
|
### Iteration 2: AbacusReact Direction Indicators
|
|
|
|
1. **Add direction indicator props to AbacusReact**
|
|
2. **Implement visual direction indicators (arrows/styling)**
|
|
3. **Create Storybook stories for direction indicators**
|
|
4. **Test various direction combinations**
|
|
|
|
### Iteration 3: Progressive TutorialPlayer
|
|
|
|
1. **Add progressive state management to TutorialPlayer**
|
|
2. **Implement step advancement logic**
|
|
3. **Coordinate instruction text with bead highlights**
|
|
4. **Test tutorial progression flow**
|
|
|
|
### Iteration 4: Integration and Polish
|
|
|
|
1. **Integrate all components in tutorial editor preview**
|
|
2. **End-to-end testing of complete progressive experience**
|
|
3. **Performance optimization**
|
|
4. **Accessibility improvements**
|
|
|
|
## Success Criteria
|
|
|
|
1. **Bead-Instruction Correspondence**: Each instruction step highlights only its relevant beads
|
|
2. **Direction Clarity**: Users can see which direction each bead needs to move
|
|
3. **Progressive Revelation**: Only current step is active, future steps are dimmed
|
|
4. **Pedagogical Alignment**: Visual progression matches mathematical decomposition
|
|
5. **99+1 Test Case**:
|
|
- Step 1: Show only hundreds bead with "up" indicator
|
|
- Step 2: Show only ones column beads with "down" indicators
|
|
- Step 3: Show only tens column beads with "down" indicators
|
|
|
|
## Technical Considerations
|
|
|
|
### Performance
|
|
|
|
- Minimize re-renders during step progression
|
|
- Efficient bead highlight calculations
|
|
- Smooth animations for step transitions
|
|
|
|
### Accessibility
|
|
|
|
- Screen reader announcements for step changes
|
|
- Keyboard navigation through steps
|
|
- High contrast direction indicators
|
|
|
|
### Backward Compatibility
|
|
|
|
- Maintain existing single-step tutorial functionality
|
|
- Graceful fallback for tutorials without multi-step data
|
|
- Preserve existing AbacusReact API surface
|
|
|
|
This plan provides a comprehensive roadmap for implementing the progressive multi-step instruction system with proper coordination between pedagogy, visual display, and user interaction.
|