bug: ActionMenu tooltip reappears after modal close (React 18 timing issue)

[takaokouji]

Problem

After opening a modal from the ActionMenu (sprite selector) and closing it, the tooltip "Choose a Sprite" reappears when it should remain hidden.

Environment:

• Affected: packages/scratch-gui (React 18)
• Working: gui/smalruby3-gui (React 16)
• Component: packages/scratch-gui/src/components/action-menu/action-menu.jsx

Steps to Reproduce

1. Start dev server and navigate to sprite selector
2. Hover mouse over ActionMenu button → tooltip "Choose a Sprite" appears
3. Move mouse up to expand action menu
4. Click any action item (e.g., "Surprise", "Paint", "Choose a Sprite") to open modal
5. Close the modal
6. Bug: Tooltip "Choose a Sprite" reappears (should stay hidden)

Investigation Results

Initial Hypothesis (Partially Correct)

Race condition between React 18 event handling and multiple setTimeout operations:

• Zero-delay setTimeout resets forceHide: false immediately
• Phantom onMouseLeave events during modal display trigger 300ms timeout
• React 18's root-level event attachment causes different timing than React 16

Actual Root Causes (Discovered Through Testing)

1. File input buttons bypass clickDelayer (line 186):

   onClick={hasFileInput ? handleClick : this.clickDelayer(handleClick)}

   • "Upload Sprite" button has fileInput, so it bypassed tooltip hiding logic
   • Only "Upload Sprite" worked correctly (file dialog steals focus)
   • Other buttons ("Surprise", "Paint", "Choose a Sprite") showed the bug

2. Automatic forceHide reset after 300ms:

   setTimeout(() => this.setState({forceHide: false}), CLOSE_DELAY);

   • forceHide: false resets while modal is still opening/closing
   • If mouse is still over ActionMenu area, ReactTooltip re-activates
   • 300ms is too short - modal takes longer to open and capture focus

3. ReactTooltip Portal rendering:

   • ReactTooltip renders in Portal outside ActionMenu DOM
   • CSS .force-hidden .tooltip doesn't affect Portal-rendered tooltips
   • Need to control ReactTooltip state programmatically

Why It Works in React 16 but Not React 18

Aspect	React 16	React 18
Event attachment	Document level	React root level
Event timing	After React synthetic events	May fire before synthetic events
Mouse event behavior	Predictable sequence	Can trigger during reconciliation
Tooltip management	Natural timing works	Requires explicit control

Final Solution

1. Ensure All Buttons Use clickDelayer (line 206)

Before:

onClick={hasFileInput ? handleClick : this.clickDelayer(handleClick)}

After:

onClick={this.clickDelayer(handleClick)}

All sub-menu buttons (including file input) now go through clickDelayer.

2. Add ignoreMouseLeave Flag (line 29)

this.ignoreMouseLeave = false;

Prevents phantom onMouseLeave events during modal display from scheduling close timeout.

3. Ignore Mouse Leave During Click (lines 55-61)

handleClosePopover () {
    if (this.ignoreMouseLeave) {
        return; // Ignore phantom events
    }
    this.closeTimeoutId = setTimeout(() => {
        ReactTooltip.hide();
        this.setState({isOpen: false});
        this.closeTimeoutId = null;
    }, CLOSE_DELAY);
}

4. Set Flag in clickDelayer (lines 99, 115)

this.ignoreMouseLeave = true;

Prevents subsequent handleClosePopover calls from scheduling timeouts.

5. Remove Automatic forceHide Reset (lines 122-124)

Before:

this.setState({forceHide: true, isOpen: false}, () => {
    setTimeout(() => this.setState({forceHide: false}), CLOSE_DELAY);
});

After:

this.setState({forceHide: true, isOpen: false});
// Don't reset forceHide automatically - wait for user to move mouse away and back

forceHide now stays true until user explicitly hovers again.

6. Reset Flags on Re-Hover (line 82)

handleToggleOpenState () {
    if (!this.state.isOpen) {
        this.ignoreMouseLeave = false;
        this.setState({
            isOpen: true,
            forceHide: false
        });
    }
}

When user moves mouse away and hovers again, flags are reset and tooltip can show normally.

Implementation Details

Modified Files

• packages/scratch-gui/src/components/action-menu/action-menu.jsx

Key Changes

1. Added ignoreMouseLeave flag to prevent phantom mouse leave events
2. All buttons use clickDelayer (removed file input bypass)
3. Removed automatic forceHide reset (manual reset on re-hover only)
4. Added flag reset in handleToggleOpenState and componentWillUnmount
5. Added debug logging (to be removed before final commit)

Behavior After Fix

Expected sequence:

1. User hovers → tooltip appears
2. User clicks sub-menu item
3. clickDelayer sets: ignoreMouseLeave=true, forceHide=true
4. ReactTooltip.hide() called
5. Modal opens (DOM changes trigger phantom onMouseLeave)
6. handleClosePopover called but IGNORES (ignoreMouseLeave=true)
7. Modal closes
8. Tooltip stays hidden ✓
9. User moves mouse away and hovers again
10. handleToggleOpenState resets flags
11. Tooltip works normally again ✓

Verification Steps

After fix:

1. Start dev server: docker compose up app
2. Hover ActionMenu → tooltip appears ✓
3. Expand menu → menu shows ✓
4. Click each sub-menu item:
   • Upload Sprite → modal opens → close → tooltip stays hidden ✓
   • Surprise → modal opens → close → tooltip stays hidden ✓
   • Paint → modal opens → close → tooltip stays hidden ✓
   • Choose a Sprite → modal opens → close → tooltip stays hidden ✓
5. Move mouse away and hover again → tooltip works normally ✓

Related Fix

Commit 7d2a8c7 fixed similar MenuBar issue using setTimeout(..., 0) pattern. This ActionMenu fix follows similar React 18 timing principles but with different implementation due to tooltip-specific requirements.

Status

✅ FIXED - All sub-menu buttons now correctly hide tooltip after modal closes. Tooltip only reappears when user explicitly re-hovers.

[takaokouji]

Root Cause Analysis Summary

After thorough investigation and testing, the root causes were identified and fixed:

1. File Input Buttons Bypassed Tooltip Control

Problem: Line 186 of action-menu.jsx had conditional logic:

onClick={hasFileInput ? handleClick : this.clickDelayer(handleClick)}

Impact:

• "Upload Sprite" button (has fileInput) bypassed clickDelayer
• Only "Upload Sprite" worked correctly because file dialog steals browser focus
• Other buttons ("Surprise", "Paint", "Choose a Sprite") exhibited the bug

Fix: All buttons now use clickDelayer:

onClick={this.clickDelayer(handleClick)}

2. Automatic forceHide Reset Was Too Early

Problem: Original code reset forceHide after 300ms:

this.setState({forceHide: true, isOpen: false}, () => {
    setTimeout(() => this.setState({forceHide: false}), CLOSE_DELAY);
});

Impact:

• 300ms is too short - modals take longer to open and capture focus
• If mouse is still over ActionMenu when forceHide: false, ReactTooltip re-activates
• Tooltip reappears while modal is still opening/visible

Fix: Removed automatic reset - forceHide stays true until user explicitly re-hovers:

this.setState({forceHide: true, isOpen: false});
// Don't reset forceHide automatically - wait for user to move mouse away and back
// forceHide will be reset in handleToggleOpenState when user hovers again

3. Phantom onMouseLeave Events in React 18

Problem: When modal opens, React reconciles DOM tree, triggering synthetic onMouseLeave events

Impact:

• handleClosePopover schedules 300ms timeout even though user didn't move mouse away
• Timeout completes → isOpen: false → tooltip becomes visible again

Fix: Added ignoreMouseLeave flag:

// In clickDelayer:
this.ignoreMouseLeave = true;

// In handleClosePopover:
if (this.ignoreMouseLeave) {
    return; // Ignore phantom events
}

4. ReactTooltip Portal Rendering

Observation: ReactTooltip renders in Portal outside ActionMenu DOM tree

Impact: CSS .force-hidden .tooltip { display: none !important; } doesn't affect Portal-rendered tooltips

Fix: Explicit ReactTooltip.hide() calls in clickDelayer and handleClosePopover

React 16 vs React 18 Difference

The bug only appears in React 18 due to event system changes:

Aspect	React 16	React 18
Event Delegation	Document level	React root level
Event Timing	After React synthetic events complete	May fire before synthetic events
DOM Reconciliation	Predictable mouse event sequence	Can trigger synthetic mouse events during reconciliation

In React 16, the natural event timing prevented these issues. React 18 requires explicit handling.

Solution Verification

Tested all sub-menu buttons:

✅ Upload Sprite → modal opens → close → tooltip stays hidden
✅ Surprise → modal opens → close → tooltip stays hidden
✅ Paint → modal opens → close → tooltip stays hidden
✅ Choose a Sprite → modal opens → close → tooltip stays hidden
✅ Move mouse away and re-hover → tooltip works normally

Commits

• db4e5f9: Initial fix attempt (delay forceHide reset and cleanup timeout)
• 543f8e5: Final fix (ignoreMouseLeave flag + manual reset + all buttons through clickDelayer)

Fixed in #31

[takaokouji]

The Essence of the Problem (Minimal Fix Analysis)

After further refinement, the fix was reduced to its absolute minimum. The following complex mechanisms were not necessary:

Removed (Unnecessary)

1. ❌ ignoreMouseLeave flag and all related logic
2. ❌ ReactTooltip.hide() call in handleClosePopover
3. ❌ Explicit phantom event handling

The True Root Cause

The bug had only two root causes:

1. File Input Buttons Bypassed clickDelayer ⭐

Original code (line 186):

onClick={hasFileInput ? handleClick : this.clickDelayer(handleClick)}

Fixed code:

onClick={this.clickDelayer(handleClick)}

Why this mattered:

• "Upload Sprite" button (has fileInput) bypassed tooltip control
• Other buttons went through clickDelayer but still had bug due to cause fix: prevent Opal from being loaded twice in tests #2

2. Automatic forceHide Reset After 300ms ⭐⭐⭐

Original code (db4e5f9 before fix):

this.setState({forceHide: true, isOpen: false}, () => {
    setTimeout(() => this.setState({forceHide: false}));
});

Intermediate fix (db4e5f9):

this.setState({forceHide: true, isOpen: false}, () => {
    setTimeout(() => this.setState({forceHide: false}), CLOSE_DELAY);
});

Final minimal fix (current):

this.setState({forceHide: true, isOpen: false});
// Don't reset forceHide automatically - wait for user to move mouse away and back

Why this is the core issue:

• When user clicks a button, modal takes time to open
• If forceHide resets to false while mouse is still over ActionMenu area, ReactTooltip re-activates
• Solution: Don't reset automatically - let user explicitly re-hover to reset

Why the Minimal Fix Works

CSS Already Handles Everything

The CSS rule (action-menu.css lines 119-121):

.force-hidden .tooltip {
    display: none !important;
}

This single CSS rule solves all problems:

1. ✅ Hides main button tooltip ("Choose a Sprite")
2. ✅ Hides sub-menu tooltips ("Upload Sprite", "Surprise", etc.)
3. ✅ Works even with React Portal rendering (ReactTooltip uses Portals)
4. ✅ Prevents tooltip reappearance during phantom mouse events

Why Phantom Events Don't Matter

Initially thought: Need to ignore phantom onMouseLeave events during modal display

Reality: Phantom events are harmless when forceHide stays true

• Phantom onMouseLeave triggers → handleClosePopover → schedules 300ms timeout
• Timeout completes → setState({isOpen: false})
• But forceHide is still true → CSS keeps tooltip hidden!

The only way tooltip can reappear is if forceHide becomes false, which now only happens on explicit re-hover.

The Elegant Solution

// On click:
this.setState({forceHide: true, isOpen: false});
// (stays true until re-hover)

// On re-hover:
this.setState({isOpen: true, forceHide: false});
// (user explicitly wants to see tooltip again)

Comparison: Before and After

Before (Buggy)

1. Click button
2. forceHide: true
3. 300ms later: forceHide: false (automatic)
4. Mouse still over ActionMenu
5. ReactTooltip detects hover → shows tooltip ❌

After (Fixed)

1. Click button
2. forceHide: true
3. (No automatic reset)
4. Modal opens/closes
5. forceHide: still true → tooltip hidden ✓
6. User moves mouse away and re-hovers
7. forceHide: false → tooltip works normally ✓

Why Initial Complex Solution Seemed Necessary

The debugging process revealed multiple symptoms that looked like separate problems:

1. Phantom onMouseLeave events → seemed to need ignoreMouseLeave flag
2. ReactTooltip re-showing → seemed to need explicit ReactTooltip.hide() calls
3. Portal rendering → seemed to need special handling

But all symptoms had one root cause: forceHide resetting too early.

Once forceHide stays true until explicit re-hover, all symptoms disappear automatically.

Lessons Learned

1. CSS !important is powerful: The existing CSS rule was already perfect
2. State lifecycle matters: Don't auto-reset state that controls critical UI behavior
3. Simplicity wins: The minimal fix is 2 changes, not 20
4. React 18 timing: Event timing issues often manifest as complex problems with simple solutions

Final Minimal Changes

From original code to fixed code:

db4e5f9 (initial fix):

• ✅ Remove auto-reset timeout in clickDelayer
• ✅ Add timeout cleanup in componentWillUnmount

No other changes needed!

Commits 543f8e5 → c3cf515 → 75d4ff9 removed all unnecessary complexity.

Impact

• Code complexity: Reduced significantly
• Maintainability: Much easier to understand
• Performance: No extra flags or event checks
• Reliability: Fewer moving parts = fewer bugs

The simplest solution is often the best solution. 🎯