Skip to content

fix(window): prevent z-index occlusion during minimize/restore flights - #916

Open
KarunyaChavan wants to merge 5 commits into
WordPress:trunkfrom
KarunyaChavan:fix/minimize-animation-z-index-occlusion
Open

KarunyaChavan wants to merge 5 commits into
WordPress:trunkfrom
KarunyaChavan:fix/minimize-animation-z-index-occlusion

Conversation

@KarunyaChavan

@KarunyaChavan KarunyaChavan commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

Closes #906
This PR fixes an issue where the genie minimize/restore animation cuts off abruptly and gets hidden behind other windows when multiple windows are open on the desktop.

Why?

Mid-Flight Restacking Occlusion:

  • When a window is minimized, the window manager synchronously shifts focus to the next visible window while the WAAPI genie animation is still actively in flight.
  • The focus change rewrites the z-index of all windows on the desktop.
  • This assigned the newly focused window a higher (or matching) z-index, causing the flying window to be obscured behind background windows before it could complete its flight path down to the dock.

Declarative Stacking Hierarchy:

  • A dedicated elevation layer was needed to guarantee that any flying window stays strictly above ordinary desktop windows (100–120) and directly underneath the dock (200) throughout the entire flight lifecycle without adding procedural branching to setZIndex().

What Changed?

  • Added --os-z-genie Design Token (assets/css/variables.css):
    • Declared --os-z-genie: 199; under body.os-active to establish a formal stacking layer for in-flight animations directly below the dock (200).
  • Created .os-window--genie-flight Rule (assets/css/window-states.css):
    • Added .os-window--genie-flight { z-index: var( --os-z-genie, 199 ) !important; } to handle flight layer elevation declaratively via CSS.
  • Managed Flight Class in Window Lifecycle (src/window/index.ts):
    • Applied .os-window--genie-flight at the start of both minimize() and restore() flights.
    • Ensured .os-window--genie-flight is stripped cleanly across all completion (onfinish), cancellation (oncancel, _cancelGenieAnimation), and early return paths.
    • Kept Window.prototype.setZIndex() pure and unblocked.

Steps for Testing

  • Multi-Window Minimize Test:
    • Open 3–4 windows on the desktop (e.g., Pages, Media Library, OS Settings).
    • Focus the topmost window and click the Minimize (-) button.
    • Verify that the minimizing window stays on top of all other windows and smoothly completes its full flight path down to its dock tile without getting cut off or hidden.
  • Multi-Window Restore Test:
    • Click the dock tile of the minimized window to restore it.
    • Verify that the window expands smoothly from the dock back to its position on top of the other open windows.
  • Single-Window Regression Check:
    • Open only 1 window and minimize/restore it.
    • Verify that the animation remains smooth and unchanged.
  • Automated Test Validation:
    • Run npm run typecheck, npm run lint, and npm run test:js to verify that all type checks, lint rules, and test suites pass.
Open WordPress Playground Preview

KarunyaChavan and others added 4 commits September 28, 2026 13:34
- When multiple windows are open, minimizing a window triggers focus() on the next visible window synchronously while the WAAPI genie animation is in flight.
- This restacks z-indices and places the minimizing window behind the newly focused window mid-flight.
- Guard setZIndex() while 'os-window--minimizing' is active so the animating window remains on top throughout its flight path to the dock.
…ght CSS token

Refactor the z-index occlusion fix from a procedural guard inside Window.setZIndex() into a declarative CSS token and class:

- Remove the `os-window--minimizing` class check from setZIndex(), keeping the method pure.
- Declare `--os-z-genie: 199` in variables.css and style `.os-window--genie-flight` in window-states.css to manage flight layer elevation purely in CSS.
- Toggle `.os-window--genie-flight` across both minimize and restore WAAPI animation lifecycles.
@KarunyaChavan
KarunyaChavan marked this pull request as ready for review September 28, 2026 13:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Window Minimize Animation Is Occluded by Other Windows When Multiple Windows Are Open

1 participant