docs: add comprehensive documentation and debug tools for progressive instruction system
PROGRESSIVE_INSTRUCTION_PLAN.md: - Complete implementation plan with 4 phases and success criteria - Technical architecture documentation - Data structure specifications and implementation approach Storybook Debug Stories: - AbacusReact.debug-arrows.stories.tsx: Simple arrow positioning debugging - AbacusReact.direction-arrows.stories.tsx: Comprehensive direction indicator showcase - Stories for testing single beads, multiple arrows, and raw SVG validation Step Advancement Test: - step-advancement.test.tsx: Isolated unit tests for step progression logic - Test component implementing full step advancement workflow - Validates expected step generation and auto-advancement behavior These tools enabled debugging and validation of the complete progressive instruction system. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Thomas Hallock
parent
8518d90e85
commit
ba1a92230f
|
|
@ -0,0 +1,244 @@
|
||||||
|
# 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.
|
||||||
|
|
@ -0,0 +1,289 @@
|
||||||
|
import type { Meta, StoryObj } from '@storybook/react';
|
||||||
|
import { AbacusReact, StepBeadHighlight } from './AbacusReact';
|
||||||
|
import React from 'react';
|
||||||
|
|
||||||
|
const meta: Meta<typeof AbacusReact> = {
|
||||||
|
title: 'Debug/Arrow Positioning',
|
||||||
|
component: AbacusReact,
|
||||||
|
parameters: {
|
||||||
|
layout: 'centered',
|
||||||
|
docs: {
|
||||||
|
description: {
|
||||||
|
component: `
|
||||||
|
# Arrow Positioning Debug
|
||||||
|
|
||||||
|
Simple stories to debug arrow centering issues.
|
||||||
|
`,
|
||||||
|
},
|
||||||
|
},
|
||||||
|
},
|
||||||
|
tags: ['autodocs'],
|
||||||
|
};
|
||||||
|
|
||||||
|
export default meta;
|
||||||
|
type Story = StoryObj<typeof AbacusReact>;
|
||||||
|
|
||||||
|
// Single earth bead with up arrow - minimal test case
|
||||||
|
export const SingleEarthBeadUp: Story = {
|
||||||
|
args: {
|
||||||
|
value: 0,
|
||||||
|
columns: 1,
|
||||||
|
scaleFactor: 4, // Large scale to see details
|
||||||
|
interactive: false,
|
||||||
|
animated: false,
|
||||||
|
colorScheme: 'place-value',
|
||||||
|
stepBeadHighlights: [{
|
||||||
|
placeValue: 0,
|
||||||
|
beadType: 'earth',
|
||||||
|
position: 0,
|
||||||
|
stepIndex: 0,
|
||||||
|
direction: 'activate',
|
||||||
|
order: 0
|
||||||
|
}],
|
||||||
|
currentStep: 0,
|
||||||
|
showDirectionIndicators: true,
|
||||||
|
},
|
||||||
|
parameters: {
|
||||||
|
docs: {
|
||||||
|
description: {
|
||||||
|
story: `
|
||||||
|
**Single Earth Bead with Up Arrow**
|
||||||
|
|
||||||
|
- Value: 0 (no beads active)
|
||||||
|
- Shows green up arrow on first earth bead
|
||||||
|
- Large scale factor for debugging
|
||||||
|
- Should be centered on the bead
|
||||||
|
`
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
// Single heaven bead with down arrow
|
||||||
|
export const SingleHeavenBeadDown: Story = {
|
||||||
|
args: {
|
||||||
|
value: 0,
|
||||||
|
columns: 1,
|
||||||
|
scaleFactor: 4,
|
||||||
|
interactive: false,
|
||||||
|
animated: false,
|
||||||
|
colorScheme: 'place-value',
|
||||||
|
stepBeadHighlights: [{
|
||||||
|
placeValue: 0,
|
||||||
|
beadType: 'heaven',
|
||||||
|
stepIndex: 0,
|
||||||
|
direction: 'activate',
|
||||||
|
order: 0
|
||||||
|
}],
|
||||||
|
currentStep: 0,
|
||||||
|
showDirectionIndicators: true,
|
||||||
|
},
|
||||||
|
parameters: {
|
||||||
|
docs: {
|
||||||
|
description: {
|
||||||
|
story: `
|
||||||
|
**Single Heaven Bead with Down Arrow**
|
||||||
|
|
||||||
|
- Value: 0 (no beads active)
|
||||||
|
- Shows red down arrow on heaven bead
|
||||||
|
- Large scale factor for debugging
|
||||||
|
- Should be centered on the bead
|
||||||
|
`
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
// Active earth bead with down arrow (deactivate)
|
||||||
|
export const ActiveEarthBeadDown: Story = {
|
||||||
|
args: {
|
||||||
|
value: 1,
|
||||||
|
columns: 1,
|
||||||
|
scaleFactor: 4,
|
||||||
|
interactive: false,
|
||||||
|
animated: false,
|
||||||
|
colorScheme: 'place-value',
|
||||||
|
stepBeadHighlights: [{
|
||||||
|
placeValue: 0,
|
||||||
|
beadType: 'earth',
|
||||||
|
position: 0,
|
||||||
|
stepIndex: 0,
|
||||||
|
direction: 'deactivate',
|
||||||
|
order: 0
|
||||||
|
}],
|
||||||
|
currentStep: 0,
|
||||||
|
showDirectionIndicators: true,
|
||||||
|
},
|
||||||
|
parameters: {
|
||||||
|
docs: {
|
||||||
|
description: {
|
||||||
|
story: `
|
||||||
|
**Active Earth Bead with Down Arrow**
|
||||||
|
|
||||||
|
- Value: 1 (first earth bead active)
|
||||||
|
- Shows red down arrow for deactivation
|
||||||
|
- Large scale factor for debugging
|
||||||
|
- Should be centered on the active bead
|
||||||
|
`
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
// Active heaven bead with up arrow (deactivate)
|
||||||
|
export const ActiveHeavenBeadUp: Story = {
|
||||||
|
args: {
|
||||||
|
value: 5,
|
||||||
|
columns: 1,
|
||||||
|
scaleFactor: 4,
|
||||||
|
interactive: false,
|
||||||
|
animated: false,
|
||||||
|
colorScheme: 'place-value',
|
||||||
|
stepBeadHighlights: [{
|
||||||
|
placeValue: 0,
|
||||||
|
beadType: 'heaven',
|
||||||
|
stepIndex: 0,
|
||||||
|
direction: 'deactivate',
|
||||||
|
order: 0
|
||||||
|
}],
|
||||||
|
currentStep: 0,
|
||||||
|
showDirectionIndicators: true,
|
||||||
|
},
|
||||||
|
parameters: {
|
||||||
|
docs: {
|
||||||
|
description: {
|
||||||
|
story: `
|
||||||
|
**Active Heaven Bead with Up Arrow**
|
||||||
|
|
||||||
|
- Value: 5 (heaven bead active)
|
||||||
|
- Shows green up arrow for deactivation
|
||||||
|
- Large scale factor for debugging
|
||||||
|
- Should be centered on the active bead
|
||||||
|
`
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
// Multiple arrows for comparison
|
||||||
|
export const MultipleArrows: Story = {
|
||||||
|
args: {
|
||||||
|
value: 0,
|
||||||
|
columns: 1,
|
||||||
|
scaleFactor: 3,
|
||||||
|
interactive: false,
|
||||||
|
animated: false,
|
||||||
|
colorScheme: 'place-value',
|
||||||
|
stepBeadHighlights: [
|
||||||
|
{
|
||||||
|
placeValue: 0,
|
||||||
|
beadType: 'heaven',
|
||||||
|
stepIndex: 0,
|
||||||
|
direction: 'activate',
|
||||||
|
order: 0
|
||||||
|
},
|
||||||
|
{
|
||||||
|
placeValue: 0,
|
||||||
|
beadType: 'earth',
|
||||||
|
position: 0,
|
||||||
|
stepIndex: 0,
|
||||||
|
direction: 'activate',
|
||||||
|
order: 1
|
||||||
|
},
|
||||||
|
{
|
||||||
|
placeValue: 0,
|
||||||
|
beadType: 'earth',
|
||||||
|
position: 1,
|
||||||
|
stepIndex: 0,
|
||||||
|
direction: 'activate',
|
||||||
|
order: 2
|
||||||
|
}
|
||||||
|
],
|
||||||
|
currentStep: 0,
|
||||||
|
showDirectionIndicators: true,
|
||||||
|
},
|
||||||
|
parameters: {
|
||||||
|
docs: {
|
||||||
|
description: {
|
||||||
|
story: `
|
||||||
|
**Multiple Arrows for Comparison**
|
||||||
|
|
||||||
|
- Shows arrows on heaven bead and first two earth beads
|
||||||
|
- All should point in correct directions
|
||||||
|
- All should be centered on their respective beads
|
||||||
|
- Helps identify if positioning is consistent across bead types
|
||||||
|
`
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
// Raw SVG test - just arrows without beads
|
||||||
|
export const RawArrowTest: Story = {
|
||||||
|
render: () => {
|
||||||
|
return (
|
||||||
|
<div style={{ textAlign: 'center', padding: '20px' }}>
|
||||||
|
<h3>Raw SVG Arrow Test</h3>
|
||||||
|
<svg width="200" height="200" style={{ border: '1px solid #ccc' }}>
|
||||||
|
{/* Grid lines for reference */}
|
||||||
|
<line x1="0" y1="100" x2="200" y2="100" stroke="#eee" strokeWidth="1" />
|
||||||
|
<line x1="100" y1="0" x2="100" y2="200" stroke="#eee" strokeWidth="1" />
|
||||||
|
|
||||||
|
{/* Center point */}
|
||||||
|
<circle cx="100" cy="100" r="2" fill="black" />
|
||||||
|
|
||||||
|
{/* Up arrow at center */}
|
||||||
|
<g transform="translate(100, 100)">
|
||||||
|
<polygon
|
||||||
|
points="-10,5 10,5 0,-10"
|
||||||
|
fill="rgba(0, 150, 0, 0.8)"
|
||||||
|
stroke="rgba(0, 100, 0, 1)"
|
||||||
|
strokeWidth="1.5"
|
||||||
|
/>
|
||||||
|
</g>
|
||||||
|
|
||||||
|
{/* Text label */}
|
||||||
|
<text x="100" y="180" textAnchor="middle" fontSize="12">
|
||||||
|
Up Arrow (should be centered at intersection)
|
||||||
|
</text>
|
||||||
|
</svg>
|
||||||
|
|
||||||
|
<svg width="200" height="200" style={{ border: '1px solid #ccc', marginLeft: '20px' }}>
|
||||||
|
{/* Grid lines for reference */}
|
||||||
|
<line x1="0" y1="100" x2="200" y2="100" stroke="#eee" strokeWidth="1" />
|
||||||
|
<line x1="100" y1="0" x2="100" y2="200" stroke="#eee" strokeWidth="1" />
|
||||||
|
|
||||||
|
{/* Center point */}
|
||||||
|
<circle cx="100" cy="100" r="2" fill="black" />
|
||||||
|
|
||||||
|
{/* Down arrow at center */}
|
||||||
|
<g transform="translate(100, 100)">
|
||||||
|
<polygon
|
||||||
|
points="-10,-10 10,-10 0,10"
|
||||||
|
fill="rgba(200, 0, 0, 0.8)"
|
||||||
|
stroke="rgba(150, 0, 0, 1)"
|
||||||
|
strokeWidth="1.5"
|
||||||
|
/>
|
||||||
|
</g>
|
||||||
|
|
||||||
|
{/* Text label */}
|
||||||
|
<text x="100" y="180" textAnchor="middle" fontSize="12">
|
||||||
|
Down Arrow (should be centered at intersection)
|
||||||
|
</text>
|
||||||
|
</svg>
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
},
|
||||||
|
parameters: {
|
||||||
|
docs: {
|
||||||
|
description: {
|
||||||
|
story: `
|
||||||
|
**Raw SVG Arrow Test**
|
||||||
|
|
||||||
|
Pure SVG arrows to verify our arrow shapes and positioning work correctly.
|
||||||
|
The arrows should be perfectly centered at the grid intersection.
|
||||||
|
`
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
@ -0,0 +1,435 @@
|
||||||
|
import type { Meta, StoryObj } from '@storybook/react';
|
||||||
|
import { action } from '@storybook/addon-actions';
|
||||||
|
import { AbacusReact, StepBeadHighlight } from './AbacusReact';
|
||||||
|
import React, { useState } from 'react';
|
||||||
|
|
||||||
|
const meta: Meta<typeof AbacusReact> = {
|
||||||
|
title: 'Soroban/AbacusReact/Direction Arrows',
|
||||||
|
component: AbacusReact,
|
||||||
|
parameters: {
|
||||||
|
layout: 'centered',
|
||||||
|
docs: {
|
||||||
|
description: {
|
||||||
|
component: `
|
||||||
|
# Direction Arrows Feature
|
||||||
|
|
||||||
|
Progressive instruction system with direction indicators for tutorial guidance.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- 🎯 **Step-based highlighting** - Show beads for current instruction step only
|
||||||
|
- ⬆️ **Direction arrows** - Visual indicators showing which direction to move beads
|
||||||
|
- 🔄 **Progressive revelation** - Steps advance as user follows instructions
|
||||||
|
- 🎨 **Correct movement logic** - Heaven beads activate down, earth beads activate up
|
||||||
|
|
||||||
|
## Arrow Logic
|
||||||
|
|
||||||
|
- **Earth beads**: 'activate' → ⬆️ (push up), 'deactivate' → ⬇️ (release down)
|
||||||
|
- **Heaven beads**: 'activate' → ⬇️ (pull down), 'deactivate' → ⬆️ (release up)
|
||||||
|
`,
|
||||||
|
},
|
||||||
|
},
|
||||||
|
},
|
||||||
|
tags: ['autodocs'],
|
||||||
|
argTypes: {
|
||||||
|
currentStep: {
|
||||||
|
control: { type: 'number', min: 0, max: 5 },
|
||||||
|
description: 'Current step index to highlight',
|
||||||
|
},
|
||||||
|
showDirectionIndicators: {
|
||||||
|
control: { type: 'boolean' },
|
||||||
|
description: 'Show direction arrows on beads',
|
||||||
|
},
|
||||||
|
},
|
||||||
|
};
|
||||||
|
|
||||||
|
export default meta;
|
||||||
|
type Story = StoryObj<typeof AbacusReact>;
|
||||||
|
|
||||||
|
// Helper function to create step bead highlights for different scenarios
|
||||||
|
const createStepBeads = (scenario: 'earth-activate' | 'heaven-activate' | 'multi-step' | 'heaven-earth-combo'): StepBeadHighlight[] => {
|
||||||
|
switch (scenario) {
|
||||||
|
case 'earth-activate':
|
||||||
|
return [
|
||||||
|
{
|
||||||
|
placeValue: 0,
|
||||||
|
beadType: 'earth',
|
||||||
|
position: 0,
|
||||||
|
stepIndex: 0,
|
||||||
|
direction: 'activate',
|
||||||
|
order: 0
|
||||||
|
}
|
||||||
|
];
|
||||||
|
|
||||||
|
case 'heaven-activate':
|
||||||
|
return [
|
||||||
|
{
|
||||||
|
placeValue: 0,
|
||||||
|
beadType: 'heaven',
|
||||||
|
stepIndex: 0,
|
||||||
|
direction: 'activate',
|
||||||
|
order: 0
|
||||||
|
}
|
||||||
|
];
|
||||||
|
|
||||||
|
case 'multi-step':
|
||||||
|
return [
|
||||||
|
// Step 0: Add heaven bead (5)
|
||||||
|
{
|
||||||
|
placeValue: 0,
|
||||||
|
beadType: 'heaven',
|
||||||
|
stepIndex: 0,
|
||||||
|
direction: 'activate',
|
||||||
|
order: 0
|
||||||
|
},
|
||||||
|
// Step 1: Remove 2 earth beads (subtract 2)
|
||||||
|
{
|
||||||
|
placeValue: 0,
|
||||||
|
beadType: 'earth',
|
||||||
|
position: 0,
|
||||||
|
stepIndex: 1,
|
||||||
|
direction: 'deactivate',
|
||||||
|
order: 0
|
||||||
|
},
|
||||||
|
{
|
||||||
|
placeValue: 0,
|
||||||
|
beadType: 'earth',
|
||||||
|
position: 1,
|
||||||
|
stepIndex: 1,
|
||||||
|
direction: 'deactivate',
|
||||||
|
order: 1
|
||||||
|
}
|
||||||
|
];
|
||||||
|
|
||||||
|
case 'heaven-earth-combo':
|
||||||
|
return [
|
||||||
|
// Step 0: Multiple beads in same step
|
||||||
|
{
|
||||||
|
placeValue: 1,
|
||||||
|
beadType: 'earth',
|
||||||
|
position: 0,
|
||||||
|
stepIndex: 0,
|
||||||
|
direction: 'activate',
|
||||||
|
order: 0
|
||||||
|
},
|
||||||
|
{
|
||||||
|
placeValue: 0,
|
||||||
|
beadType: 'heaven',
|
||||||
|
stepIndex: 0,
|
||||||
|
direction: 'deactivate',
|
||||||
|
order: 1
|
||||||
|
},
|
||||||
|
{
|
||||||
|
placeValue: 0,
|
||||||
|
beadType: 'earth',
|
||||||
|
position: 0,
|
||||||
|
stepIndex: 0,
|
||||||
|
direction: 'deactivate',
|
||||||
|
order: 2
|
||||||
|
}
|
||||||
|
];
|
||||||
|
|
||||||
|
default:
|
||||||
|
return [];
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
export const EarthBeadActivate: Story = {
|
||||||
|
args: {
|
||||||
|
value: 0,
|
||||||
|
columns: 1,
|
||||||
|
scaleFactor: 3,
|
||||||
|
interactive: true,
|
||||||
|
animated: true,
|
||||||
|
colorScheme: 'place-value',
|
||||||
|
colorPalette: 'default',
|
||||||
|
stepBeadHighlights: createStepBeads('earth-activate'),
|
||||||
|
currentStep: 0,
|
||||||
|
showDirectionIndicators: true,
|
||||||
|
onValueChange: action('value-changed'),
|
||||||
|
},
|
||||||
|
parameters: {
|
||||||
|
docs: {
|
||||||
|
description: {
|
||||||
|
story: `
|
||||||
|
**Earth Bead Activation (0 + 1)**
|
||||||
|
|
||||||
|
- Shows green up arrow on first earth bead
|
||||||
|
- Earth beads activate by moving UP
|
||||||
|
- Click the highlighted bead to see the value change to 1
|
||||||
|
`
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
export const HeavenBeadActivate: Story = {
|
||||||
|
args: {
|
||||||
|
value: 0,
|
||||||
|
columns: 1,
|
||||||
|
scaleFactor: 3,
|
||||||
|
interactive: true,
|
||||||
|
animated: true,
|
||||||
|
colorScheme: 'place-value',
|
||||||
|
stepBeadHighlights: createStepBeads('heaven-activate'),
|
||||||
|
currentStep: 0,
|
||||||
|
showDirectionIndicators: true,
|
||||||
|
onValueChange: action('value-changed'),
|
||||||
|
},
|
||||||
|
parameters: {
|
||||||
|
docs: {
|
||||||
|
description: {
|
||||||
|
story: `
|
||||||
|
**Heaven Bead Activation (0 + 5)**
|
||||||
|
|
||||||
|
- Shows red down arrow on heaven bead
|
||||||
|
- Heaven beads activate by moving DOWN
|
||||||
|
- Click the highlighted bead to see the value change to 5
|
||||||
|
`
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
export const MultiStepSequence: Story = {
|
||||||
|
args: {
|
||||||
|
value: 2,
|
||||||
|
columns: 1,
|
||||||
|
scaleFactor: 3,
|
||||||
|
interactive: true,
|
||||||
|
animated: true,
|
||||||
|
colorScheme: 'place-value',
|
||||||
|
stepBeadHighlights: createStepBeads('multi-step'),
|
||||||
|
currentStep: 0,
|
||||||
|
showDirectionIndicators: true,
|
||||||
|
onValueChange: action('value-changed'),
|
||||||
|
},
|
||||||
|
parameters: {
|
||||||
|
docs: {
|
||||||
|
description: {
|
||||||
|
story: `
|
||||||
|
**Multi-Step Complement (2 + 3 = 5)**
|
||||||
|
|
||||||
|
Step progression using five complement: 3 = 5 - 2
|
||||||
|
|
||||||
|
**Step 0**: Red down arrow on heaven bead (add 5)
|
||||||
|
**Step 1**: Red down arrows on earth beads (remove 2)
|
||||||
|
|
||||||
|
Use the currentStep control to see different steps highlighted.
|
||||||
|
`
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
export const ComplexOperation: Story = {
|
||||||
|
args: {
|
||||||
|
value: 7,
|
||||||
|
columns: 2,
|
||||||
|
scaleFactor: 2.5,
|
||||||
|
interactive: true,
|
||||||
|
animated: true,
|
||||||
|
colorScheme: 'place-value',
|
||||||
|
stepBeadHighlights: createStepBeads('heaven-earth-combo'),
|
||||||
|
currentStep: 0,
|
||||||
|
showDirectionIndicators: true,
|
||||||
|
onValueChange: action('value-changed'),
|
||||||
|
},
|
||||||
|
parameters: {
|
||||||
|
docs: {
|
||||||
|
description: {
|
||||||
|
story: `
|
||||||
|
**Complex Multi-Column Operation**
|
||||||
|
|
||||||
|
Shows multiple beads across different columns and types:
|
||||||
|
- Green up arrow on tens earth bead (activate)
|
||||||
|
- Red up arrow on ones heaven bead (deactivate)
|
||||||
|
- Red down arrow on ones earth bead (deactivate)
|
||||||
|
|
||||||
|
All beads are part of step 0, showing simultaneous actions.
|
||||||
|
`
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
// Interactive story to demonstrate step progression
|
||||||
|
export const InteractiveStepProgression: Story = {
|
||||||
|
render: (args) => {
|
||||||
|
const [currentStep, setCurrentStep] = useState(0);
|
||||||
|
const [value, setValue] = useState(2);
|
||||||
|
|
||||||
|
const stepBeads = createStepBeads('multi-step');
|
||||||
|
const maxSteps = Math.max(...stepBeads.map(bead => bead.stepIndex)) + 1;
|
||||||
|
|
||||||
|
const handleValueChange = (newValue: number) => {
|
||||||
|
setValue(newValue);
|
||||||
|
action('value-changed')(newValue);
|
||||||
|
|
||||||
|
// Auto-advance step when value changes (simple demo logic)
|
||||||
|
if (currentStep < maxSteps - 1) {
|
||||||
|
setTimeout(() => setCurrentStep(prev => prev + 1), 500);
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
const resetDemo = () => {
|
||||||
|
setValue(2);
|
||||||
|
setCurrentStep(0);
|
||||||
|
};
|
||||||
|
|
||||||
|
return (
|
||||||
|
<div style={{ textAlign: 'center' }}>
|
||||||
|
<AbacusReact
|
||||||
|
{...args}
|
||||||
|
value={value}
|
||||||
|
currentStep={currentStep}
|
||||||
|
stepBeadHighlights={stepBeads}
|
||||||
|
onValueChange={handleValueChange}
|
||||||
|
/>
|
||||||
|
<div style={{ marginTop: '20px', fontSize: '14px', color: '#666' }}>
|
||||||
|
<p><strong>Step {currentStep + 1} of {maxSteps}</strong></p>
|
||||||
|
<p>Value: {value}</p>
|
||||||
|
<button
|
||||||
|
onClick={resetDemo}
|
||||||
|
style={{
|
||||||
|
padding: '8px 16px',
|
||||||
|
marginTop: '10px',
|
||||||
|
backgroundColor: '#4A90E2',
|
||||||
|
color: 'white',
|
||||||
|
border: 'none',
|
||||||
|
borderRadius: '4px',
|
||||||
|
cursor: 'pointer'
|
||||||
|
}}
|
||||||
|
>
|
||||||
|
Reset Demo
|
||||||
|
</button>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
},
|
||||||
|
args: {
|
||||||
|
columns: 1,
|
||||||
|
scaleFactor: 3,
|
||||||
|
interactive: true,
|
||||||
|
animated: true,
|
||||||
|
colorScheme: 'place-value',
|
||||||
|
showDirectionIndicators: true,
|
||||||
|
},
|
||||||
|
parameters: {
|
||||||
|
docs: {
|
||||||
|
description: {
|
||||||
|
story: `
|
||||||
|
**Interactive Step Progression Demo**
|
||||||
|
|
||||||
|
Demonstrates automatic step advancement:
|
||||||
|
1. Start with value 2
|
||||||
|
2. Click the heaven bead (red down arrow) to add 5 → value becomes 7
|
||||||
|
3. Step automatically advances to show earth bead deactivation arrows
|
||||||
|
4. Click earth beads to remove 2 → final value becomes 5
|
||||||
|
|
||||||
|
This simulates the tutorial experience where steps progress as users follow instructions.
|
||||||
|
`
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
// Static showcase of all arrow types
|
||||||
|
export const AllArrowTypes: Story = {
|
||||||
|
render: () => {
|
||||||
|
const earthActivate: StepBeadHighlight[] = [
|
||||||
|
{ placeValue: 0, beadType: 'earth', position: 0, stepIndex: 0, direction: 'activate' }
|
||||||
|
];
|
||||||
|
|
||||||
|
const earthDeactivate: StepBeadHighlight[] = [
|
||||||
|
{ placeValue: 0, beadType: 'earth', position: 0, stepIndex: 0, direction: 'deactivate' }
|
||||||
|
];
|
||||||
|
|
||||||
|
const heavenActivate: StepBeadHighlight[] = [
|
||||||
|
{ placeValue: 0, beadType: 'heaven', stepIndex: 0, direction: 'activate' }
|
||||||
|
];
|
||||||
|
|
||||||
|
const heavenDeactivate: StepBeadHighlight[] = [
|
||||||
|
{ placeValue: 0, beadType: 'heaven', stepIndex: 0, direction: 'deactivate' }
|
||||||
|
];
|
||||||
|
|
||||||
|
return (
|
||||||
|
<div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, 1fr)', gap: '20px', textAlign: 'center' }}>
|
||||||
|
<div>
|
||||||
|
<h4>Earth Activate (⬆️)</h4>
|
||||||
|
<AbacusReact
|
||||||
|
value={0}
|
||||||
|
columns={1}
|
||||||
|
scaleFactor={2}
|
||||||
|
stepBeadHighlights={earthActivate}
|
||||||
|
currentStep={0}
|
||||||
|
showDirectionIndicators={true}
|
||||||
|
/>
|
||||||
|
<p style={{ fontSize: '12px', color: '#666', marginTop: '8px' }}>
|
||||||
|
Green up arrow - push earth bead up to activate
|
||||||
|
</p>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div>
|
||||||
|
<h4>Earth Deactivate (⬇️)</h4>
|
||||||
|
<AbacusReact
|
||||||
|
value={1}
|
||||||
|
columns={1}
|
||||||
|
scaleFactor={2}
|
||||||
|
stepBeadHighlights={earthDeactivate}
|
||||||
|
currentStep={0}
|
||||||
|
showDirectionIndicators={true}
|
||||||
|
/>
|
||||||
|
<p style={{ fontSize: '12px', color: '#666', marginTop: '8px' }}>
|
||||||
|
Red down arrow - release earth bead down to deactivate
|
||||||
|
</p>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div>
|
||||||
|
<h4>Heaven Activate (⬇️)</h4>
|
||||||
|
<AbacusReact
|
||||||
|
value={0}
|
||||||
|
columns={1}
|
||||||
|
scaleFactor={2}
|
||||||
|
stepBeadHighlights={heavenActivate}
|
||||||
|
currentStep={0}
|
||||||
|
showDirectionIndicators={true}
|
||||||
|
/>
|
||||||
|
<p style={{ fontSize: '12px', color: '#666', marginTop: '8px' }}>
|
||||||
|
Red down arrow - pull heaven bead down to activate
|
||||||
|
</p>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div>
|
||||||
|
<h4>Heaven Deactivate (⬆️)</h4>
|
||||||
|
<AbacusReact
|
||||||
|
value={5}
|
||||||
|
columns={1}
|
||||||
|
scaleFactor={2}
|
||||||
|
stepBeadHighlights={heavenDeactivate}
|
||||||
|
currentStep={0}
|
||||||
|
showDirectionIndicators={true}
|
||||||
|
/>
|
||||||
|
<p style={{ fontSize: '12px', color: '#666', marginTop: '8px' }}>
|
||||||
|
Green up arrow - release heaven bead up to deactivate
|
||||||
|
</p>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
},
|
||||||
|
parameters: {
|
||||||
|
docs: {
|
||||||
|
description: {
|
||||||
|
story: `
|
||||||
|
**Complete Arrow Reference**
|
||||||
|
|
||||||
|
Shows all four arrow types with correct colors and directions:
|
||||||
|
|
||||||
|
- **Green arrows**: Positive/activating actions
|
||||||
|
- **Red arrows**: Negative/deactivating actions
|
||||||
|
- **Direction**: Based on physical bead movement direction
|
||||||
|
`
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
@ -0,0 +1,294 @@
|
||||||
|
import React, { useState, useEffect, useRef, useCallback, useMemo } from 'react';
|
||||||
|
import { render, fireEvent, screen } from '@testing-library/react';
|
||||||
|
import { vi } from 'vitest';
|
||||||
|
|
||||||
|
// Mock the instruction generator
|
||||||
|
const generateAbacusInstructions = (startValue: number, targetValue: number) => {
|
||||||
|
// Mock implementation for 3+14=17 case
|
||||||
|
if (startValue === 3 && targetValue === 8) {
|
||||||
|
return {
|
||||||
|
stepBeadHighlights: [{
|
||||||
|
placeValue: 0,
|
||||||
|
beadType: 'heaven' as const,
|
||||||
|
stepIndex: 0,
|
||||||
|
direction: 'activate' as const,
|
||||||
|
order: 0
|
||||||
|
}]
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
if (startValue === 8 && targetValue === 18) {
|
||||||
|
return {
|
||||||
|
stepBeadHighlights: [{
|
||||||
|
placeValue: 1,
|
||||||
|
beadType: 'earth' as const,
|
||||||
|
position: 0,
|
||||||
|
stepIndex: 0,
|
||||||
|
direction: 'activate' as const,
|
||||||
|
order: 0
|
||||||
|
}]
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
if (startValue === 18 && targetValue === 17) {
|
||||||
|
return {
|
||||||
|
stepBeadHighlights: [{
|
||||||
|
placeValue: 0,
|
||||||
|
beadType: 'earth' as const,
|
||||||
|
position: 0,
|
||||||
|
stepIndex: 0,
|
||||||
|
direction: 'deactivate' as const,
|
||||||
|
order: 0
|
||||||
|
}]
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
return { stepBeadHighlights: [] };
|
||||||
|
};
|
||||||
|
|
||||||
|
// Test component that implements the step advancement logic
|
||||||
|
const StepAdvancementTest: React.FC = () => {
|
||||||
|
const [currentValue, setCurrentValue] = useState(3);
|
||||||
|
const [currentMultiStep, setCurrentMultiStep] = useState(0);
|
||||||
|
|
||||||
|
const lastValueForStepAdvancement = useRef<number>(currentValue);
|
||||||
|
const userHasInteracted = useRef<boolean>(false);
|
||||||
|
|
||||||
|
// Mock current step data (3 + 14 = 17)
|
||||||
|
const currentStep = {
|
||||||
|
startValue: 3,
|
||||||
|
targetValue: 17,
|
||||||
|
stepBeadHighlights: [
|
||||||
|
{
|
||||||
|
placeValue: 0,
|
||||||
|
beadType: 'heaven' as const,
|
||||||
|
stepIndex: 0,
|
||||||
|
direction: 'activate' as const,
|
||||||
|
order: 0
|
||||||
|
},
|
||||||
|
{
|
||||||
|
placeValue: 1,
|
||||||
|
beadType: 'earth' as const,
|
||||||
|
position: 0,
|
||||||
|
stepIndex: 1,
|
||||||
|
direction: 'activate' as const,
|
||||||
|
order: 0
|
||||||
|
},
|
||||||
|
{
|
||||||
|
placeValue: 0,
|
||||||
|
beadType: 'earth' as const,
|
||||||
|
position: 0,
|
||||||
|
stepIndex: 2,
|
||||||
|
direction: 'deactivate' as const,
|
||||||
|
order: 0
|
||||||
|
}
|
||||||
|
],
|
||||||
|
totalSteps: 3
|
||||||
|
};
|
||||||
|
|
||||||
|
// Define the static expected steps
|
||||||
|
const expectedSteps = useMemo(() => {
|
||||||
|
if (!currentStep.stepBeadHighlights || !currentStep.totalSteps || currentStep.totalSteps <= 1) {
|
||||||
|
return [];
|
||||||
|
}
|
||||||
|
|
||||||
|
const stepIndices = [...new Set(currentStep.stepBeadHighlights.map(bead => bead.stepIndex))].sort();
|
||||||
|
const steps = [];
|
||||||
|
let value = currentStep.startValue;
|
||||||
|
|
||||||
|
if (currentStep.startValue === 3 && currentStep.targetValue === 17) {
|
||||||
|
const milestones = [8, 18, 17];
|
||||||
|
for (let i = 0; i < stepIndices.length && i < milestones.length; i++) {
|
||||||
|
steps.push({
|
||||||
|
index: i,
|
||||||
|
stepIndex: stepIndices[i],
|
||||||
|
targetValue: milestones[i],
|
||||||
|
startValue: value,
|
||||||
|
description: `Step ${i + 1}`
|
||||||
|
});
|
||||||
|
value = milestones[i];
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
console.log('📋 Generated expected steps:', steps);
|
||||||
|
return steps;
|
||||||
|
}, []);
|
||||||
|
|
||||||
|
// Get arrows for immediate next action
|
||||||
|
const getCurrentStepBeads = useCallback(() => {
|
||||||
|
if (currentValue === currentStep.targetValue) return undefined;
|
||||||
|
if (expectedSteps.length === 0) return currentStep.stepBeadHighlights;
|
||||||
|
|
||||||
|
const currentExpectedStep = expectedSteps[currentMultiStep];
|
||||||
|
if (!currentExpectedStep) return undefined;
|
||||||
|
|
||||||
|
try {
|
||||||
|
const instruction = generateAbacusInstructions(currentValue, currentExpectedStep.targetValue);
|
||||||
|
const immediateAction = instruction.stepBeadHighlights?.filter(bead => bead.stepIndex === 0);
|
||||||
|
|
||||||
|
console.log('🎯 Expected step progression:', {
|
||||||
|
currentValue,
|
||||||
|
expectedStepIndex: currentMultiStep,
|
||||||
|
expectedStepTarget: currentExpectedStep.targetValue,
|
||||||
|
expectedStepDescription: currentExpectedStep.description,
|
||||||
|
immediateActionBeads: immediateAction?.length || 0,
|
||||||
|
totalExpectedSteps: expectedSteps.length
|
||||||
|
});
|
||||||
|
|
||||||
|
return immediateAction && immediateAction.length > 0 ? immediateAction : undefined;
|
||||||
|
} catch (error) {
|
||||||
|
console.warn('⚠️ Failed to generate step guidance:', error);
|
||||||
|
return undefined;
|
||||||
|
}
|
||||||
|
}, [currentValue, expectedSteps, currentMultiStep]);
|
||||||
|
|
||||||
|
// Step advancement logic
|
||||||
|
useEffect(() => {
|
||||||
|
const valueChanged = currentValue !== lastValueForStepAdvancement.current;
|
||||||
|
const currentExpectedStep = expectedSteps[currentMultiStep];
|
||||||
|
|
||||||
|
console.log('🔍 Expected step advancement check:', {
|
||||||
|
currentValue,
|
||||||
|
lastValue: lastValueForStepAdvancement.current,
|
||||||
|
valueChanged,
|
||||||
|
userHasInteracted: userHasInteracted.current,
|
||||||
|
expectedStepIndex: currentMultiStep,
|
||||||
|
expectedStepTarget: currentExpectedStep?.targetValue,
|
||||||
|
expectedStepReached: currentExpectedStep ? currentValue === currentExpectedStep.targetValue : false,
|
||||||
|
totalExpectedSteps: expectedSteps.length,
|
||||||
|
finalTargetReached: currentValue === currentStep?.targetValue
|
||||||
|
});
|
||||||
|
|
||||||
|
if (valueChanged && userHasInteracted.current && expectedSteps.length > 0 && currentExpectedStep) {
|
||||||
|
if (currentValue === currentExpectedStep.targetValue) {
|
||||||
|
const hasMoreExpectedSteps = currentMultiStep < expectedSteps.length - 1;
|
||||||
|
|
||||||
|
console.log('🎯 Expected step completed:', {
|
||||||
|
completedStep: currentMultiStep,
|
||||||
|
targetReached: currentExpectedStep.targetValue,
|
||||||
|
hasMoreSteps: hasMoreExpectedSteps,
|
||||||
|
willAdvance: hasMoreExpectedSteps
|
||||||
|
});
|
||||||
|
|
||||||
|
if (hasMoreExpectedSteps) {
|
||||||
|
const timeoutId = setTimeout(() => {
|
||||||
|
console.log('⚡ Advancing to next expected step:', currentMultiStep, '→', currentMultiStep + 1);
|
||||||
|
setCurrentMultiStep(prev => prev + 1);
|
||||||
|
lastValueForStepAdvancement.current = currentValue;
|
||||||
|
}, 100); // Shorter delay for testing
|
||||||
|
|
||||||
|
return () => clearTimeout(timeoutId);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}, [currentValue, currentMultiStep, expectedSteps]);
|
||||||
|
|
||||||
|
// Update reference when step changes
|
||||||
|
useEffect(() => {
|
||||||
|
lastValueForStepAdvancement.current = currentValue;
|
||||||
|
userHasInteracted.current = false;
|
||||||
|
}, [currentMultiStep]);
|
||||||
|
|
||||||
|
const handleValueChange = (newValue: number) => {
|
||||||
|
userHasInteracted.current = true;
|
||||||
|
setCurrentValue(newValue);
|
||||||
|
};
|
||||||
|
|
||||||
|
const currentStepBeads = getCurrentStepBeads();
|
||||||
|
|
||||||
|
return (
|
||||||
|
<div data-testid="step-test">
|
||||||
|
<div data-testid="current-value">{currentValue}</div>
|
||||||
|
<div data-testid="expected-step-index">{currentMultiStep}</div>
|
||||||
|
<div data-testid="expected-steps-length">{expectedSteps.length}</div>
|
||||||
|
<div data-testid="current-expected-target">
|
||||||
|
{expectedSteps[currentMultiStep]?.targetValue || 'N/A'}
|
||||||
|
</div>
|
||||||
|
<div data-testid="has-step-beads">{currentStepBeads ? 'yes' : 'no'}</div>
|
||||||
|
|
||||||
|
<button
|
||||||
|
data-testid="set-value-8"
|
||||||
|
onClick={() => handleValueChange(8)}
|
||||||
|
>
|
||||||
|
Set Value to 8
|
||||||
|
</button>
|
||||||
|
<button
|
||||||
|
data-testid="set-value-18"
|
||||||
|
onClick={() => handleValueChange(18)}
|
||||||
|
>
|
||||||
|
Set Value to 18
|
||||||
|
</button>
|
||||||
|
<button
|
||||||
|
data-testid="set-value-17"
|
||||||
|
onClick={() => handleValueChange(17)}
|
||||||
|
>
|
||||||
|
Set Value to 17
|
||||||
|
</button>
|
||||||
|
|
||||||
|
<div data-testid="expected-steps">
|
||||||
|
{JSON.stringify(expectedSteps)}
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
};
|
||||||
|
|
||||||
|
// Test cases
|
||||||
|
describe('Step Advancement Logic', () => {
|
||||||
|
beforeEach(() => {
|
||||||
|
vi.clearAllMocks();
|
||||||
|
console.log = vi.fn();
|
||||||
|
});
|
||||||
|
|
||||||
|
test('should generate expected steps for 3+14=17', () => {
|
||||||
|
render(<StepAdvancementTest />);
|
||||||
|
|
||||||
|
expect(screen.getByTestId('expected-steps-length')).toHaveTextContent('3');
|
||||||
|
expect(screen.getByTestId('current-expected-target')).toHaveTextContent('8');
|
||||||
|
expect(screen.getByTestId('expected-step-index')).toHaveTextContent('0');
|
||||||
|
});
|
||||||
|
|
||||||
|
test('should advance from step 0 to step 1 when reaching value 8', async () => {
|
||||||
|
render(<StepAdvancementTest />);
|
||||||
|
|
||||||
|
// Initial state
|
||||||
|
expect(screen.getByTestId('current-value')).toHaveTextContent('3');
|
||||||
|
expect(screen.getByTestId('expected-step-index')).toHaveTextContent('0');
|
||||||
|
expect(screen.getByTestId('current-expected-target')).toHaveTextContent('8');
|
||||||
|
|
||||||
|
// Click to set value to 8
|
||||||
|
fireEvent.click(screen.getByTestId('set-value-8'));
|
||||||
|
|
||||||
|
// Should still be step 0 immediately
|
||||||
|
expect(screen.getByTestId('current-value')).toHaveTextContent('8');
|
||||||
|
expect(screen.getByTestId('expected-step-index')).toHaveTextContent('0');
|
||||||
|
|
||||||
|
// Wait for timeout to advance step
|
||||||
|
await new Promise(resolve => setTimeout(resolve, 150));
|
||||||
|
|
||||||
|
// Should now be step 1
|
||||||
|
expect(screen.getByTestId('expected-step-index')).toHaveTextContent('1');
|
||||||
|
expect(screen.getByTestId('current-expected-target')).toHaveTextContent('18');
|
||||||
|
});
|
||||||
|
|
||||||
|
test('should advance through all steps', async () => {
|
||||||
|
render(<StepAdvancementTest />);
|
||||||
|
|
||||||
|
// Step 0 → 1 (3 → 8)
|
||||||
|
fireEvent.click(screen.getByTestId('set-value-8'));
|
||||||
|
await new Promise(resolve => setTimeout(resolve, 150));
|
||||||
|
expect(screen.getByTestId('expected-step-index')).toHaveTextContent('1');
|
||||||
|
|
||||||
|
// Step 1 → 2 (8 → 18)
|
||||||
|
fireEvent.click(screen.getByTestId('set-value-18'));
|
||||||
|
await new Promise(resolve => setTimeout(resolve, 150));
|
||||||
|
expect(screen.getByTestId('expected-step-index')).toHaveTextContent('2');
|
||||||
|
|
||||||
|
// Step 2 → complete (18 → 17)
|
||||||
|
fireEvent.click(screen.getByTestId('set-value-17'));
|
||||||
|
await new Promise(resolve => setTimeout(resolve, 150));
|
||||||
|
// Should stay at step 2 since it's the last step
|
||||||
|
expect(screen.getByTestId('expected-step-index')).toHaveTextContent('2');
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
export default StepAdvancementTest;
|
||||||
Loading…
Reference in New Issue