fix(v7-q12): HelpModal via createPortal(document.body) escapes transformed ancestors

apstenku123 · apstenku123 · commit d887c2d472a3 · 2026-05-23T21:40:36.000+02:00
The help popup was being positioned relative to the Palette tile (or
any other transformed ancestor like React Flow canvas) instead of the
viewport. Per CSS spec, position:fixed is relative to the nearest
*transformed* ancestor, not always the viewport — so React Flow's
.react-flow__viewport (with transform: translate/scale) re-rooted the
fixed-position frame and the modal landed inside whatever node hosted
the ? icon.

Fix: render the modal markup via createPortal(modal, document.body)
so the DOM tree is reparented to &lt;body&gt;, where no transform ancestor
exists. SSR / test envs without document fall back to inline render.

Tests (vbgui/tests/HelpModalPortal.test.tsx, 2/2 PASS):
- opening a brick ? mounts the modal under document.body, NOT inside
  the Palette aside or the render container
- opening an adapter ? portals out the same way

Regression: vbgui vitest 509 -&gt; 511 (+2) PASS.
diff --git a/vbgui/src/components/HelpIcon.tsx b/vbgui/src/components/HelpIcon.tsx
@@ -3,6 +3,7 @@
 // not gated on touching the component being explained.
 
 import { useState } from "react";
+import { createPortal } from "react-dom";
 import { TENSOR_DIAGRAMS } from "./diagrams";
 import { T } from "@/theme";
 
@@ -930,8 +931,13 @@ export interface HelpModalProps {
 
 export function HelpModal({ topic, onClose }: HelpModalProps): JSX.Element {
   const entry = HELP_TOPICS[topic];
-  
-  return (
+
+  // V7-Q12: render via createPortal(document.body) so the modal escapes
+  // any transformed ancestor (React Flow canvas, palette, anything
+  // with a CSS transform). Without this, position:fixed is positioned
+  // relative to the nearest transformed ancestor (per CSS spec), which
+  // pinned the modal inside the palette tile instead of the viewport.
+  const modal = (
     <div
       data-testid="help-modal-backdrop"
       role="dialog"
@@ -1158,6 +1164,10 @@ export function HelpModal({ topic, onClose }: HelpModalProps): JSX.Element {
       </div>
     </div>
   );
+
+  // SSR / test envs without a document fall back to inline rendering.
+  if (typeof document === "undefined") return modal;
+  return createPortal(modal, document.body);
 }
 
 function Section({
diff --git a/vbgui/tests/HelpModalPortal.test.tsx b/vbgui/tests/HelpModalPortal.test.tsx
@@ -0,0 +1,31 @@
+import { describe, it, expect } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { Palette } from "@/components/Palette";
+
+describe("V7-Q12 HelpModal renders via createPortal(document.body)", () => {
+  it("opening a brick ? mounts the modal under document.body, "
+     + "NOT inside the Palette aside", () => {
+    const { container } = render(<Palette />);
+
+    fireEvent.click(screen.getByTestId("help-icon-brick_attention"));
+
+    const modal = screen.getByTestId("help-modal-brick_attention");
+    const palette = screen.getByTestId("palette");
+
+    // The portal target is document.body — the modal MUST NOT be
+    // inside the palette (or anywhere in the render container).
+    expect(palette.contains(modal)).toBe(false);
+    expect(container.contains(modal)).toBe(false);
+
+    // It must be somewhere under document.body though.
+    expect(document.body.contains(modal)).toBe(true);
+  });
+
+  it("opening an adapter ? also portals out", () => {
+    const { container } = render(<Palette />);
+    fireEvent.click(screen.getByTestId("help-icon-adapter_rmsnorm"));
+    const modal = screen.getByTestId("help-modal-adapter_rmsnorm");
+    expect(container.contains(modal)).toBe(false);
+    expect(document.body.contains(modal)).toBe(true);
+  });
+});
