Skip to content

PULL_REQUEST_DRAFT.md

Latest commit

 

History

History
148 lines (115 loc) · 5.27 KB

PULL_REQUEST_DRAFT.md

File metadata and controls

148 lines (115 loc) · 5.27 KB

feat: Add Interactive First Project Tutorial with Step Validation

Summary

This PR introduces an interactive step-by-step tutorial that guides new users through creating their first Music Blocks project. Unlike the existing static help tour where users simply click through slides, this tutorial validates user actions and only allows progression when each step is completed.

Problem

New users often struggle with Music Blocks' learning curve:

  • They don't understand the block-based programming paradigm
  • They can't find where to start
  • They get overwhelmed by the many palettes and options
  • The existing help tour shows information but doesn't ensure users actually perform the actions

Solution

An interactive tutorial system featuring:

Core Features

  • 10 guided steps - From finding the Start block to playing your first melody
  • Action validation - The "Next" button only enables when the user completes the required action
  • Visual highlighting - Spotlight effect focuses attention on the relevant UI element
  • Real-time feedback - Status indicators show pending (⏳) vs completed (✅) actions
  • Smart overlay - Reduced opacity during drag-and-drop steps to allow full canvas/palette interaction

Tutorial Flow

Step Task Validation
1 Find the Start Block Auto-complete (observation)
2 Open Rhythm Palette Detects palette is open
3 Drag a Note Block Counts new blocks on canvas
4 Connect Note to Start Checks block connections
5 Press Play Detects play button click
6 Open Pitch Palette Detects palette is open
7 Add Pitch to Note Traverses block hierarchy
8 Play Again Detects play button click
9 Add More Notes Optional, auto-complete
10 Congratulations Tutorial complete

Changes

New Files

  • js/tutorial/FirstProjectTutorial.js - The main interactive tutorial class with:
    • Step definitions with validators
    • Overlay/spotlight/tooltip management
    • Action detection methods for palettes, blocks, and connections

Modified Files

  • js/widgets/help.js - Added "🚀 Start Interactive Tutorial" button on the First Project card
  • js/turtledefs.js - Added tutorial introduction cards to HELPCONTENT
  • index.html - Added script reference for FirstProjectTutorial.js

Screenshots

Demo

Technical Details

Validator Architecture

Each tutorial step has a validator function that returns true when the action is complete:

{
    title: _("Step 3: Drag a Note Block"),
    content: _("Find the 'Note' block and drag it onto the canvas."),
    target: () => this._getCanvas(),
    validator: () => this._hasMoreBlocks(),
    allowInteraction: true, // Reduces overlay for drag-and-drop
    onStart: () => { this._initialNoteCount = this._countBlocksByName("newnote"); }
}

Key Methods

  • _isPaletteOpen(paletteName) - Checks if a specific palette is currently open
  • _hasMoreBlocks() - Detects if new blocks were added since step started
  • _isBlockConnectedToStart(blockName) - Verifies block connections
  • _hasPitchInNote() - Traverses block hierarchy to find pitch inside note

Interaction Handling

Steps that require dragging blocks set allowInteraction: true, which:

  • Reduces overlay opacity from 60% to 20%
  • Ensures spotlight doesn't block mouse events
  • Allows users to interact with both palettes and canvas

Testing

Manual Testing Checklist

  • Step 1: Start block is visible on canvas
  • Step 2: Clicking Rhythm palette enables Next
  • Step 3: Dragging Note block to canvas enables Next
  • Step 4: Connecting Note to Start enables Next
  • Step 5: Clicking Play enables Next
  • Step 6: Clicking Pitch palette enables Next
  • Step 7: Dragging Pitch inside Note enables Next
  • Step 8: Clicking Play again enables Next
  • Step 9: Auto-completes (optional step)
  • Step 10: Shows congratulations, Finish closes tutorial

Edge Cases

  • Tutorial can be closed at any time via X button
  • Back button navigates to previous steps
  • Validators work with existing blocks on canvas
  • Mobile/tablet touch interactions (needs testing)

Accessibility

  • Uses semantic HTML for buttons
  • Clear visual indicators for current step
  • Close button available at all times
  • Future improvement: Add keyboard navigation (Esc to close, arrow keys)

Browser Compatibility

Tested on:

  • Chrome (latest)
  • Firefox (needs testing)
  • Safari (needs testing)
  • Edge (needs testing)

Related Issues

This PR addresses the need for better new user onboarding in Music Blocks.

Checklist

  • Code follows project style guidelines
  • Self-reviewed the code
  • Added comments for complex logic
  • No console errors during tutorial
  • Added screenshots/demo
  • Tested on multiple browsers

Note: This is a draft PR. Please add screenshots and complete the testing checklist before marking as ready for review.