Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(ui): raise floating layers above modals so selects open in front (#2173)

JG Trompd94a805293eb
diff --git a/packages/ui/__tests__/z-layering.test.ts b/packages/ui/__tests__/z-layering.test.ts
new file mode 100644
index 000000000..4204c040f
--- /dev/null
+++ b/packages/ui/__tests__/z-layering.test.ts
@@ -0,0 +1,132 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Ordering guard for the `--z-*` scale.
+ *
+ * `token-drift.test.ts` pins that a token *exists*. This pins the one thing
+ * about the z scale that carries meaning: the order.
+ *
+ * The failure it exists to catch is silent. Radix portals Select, Popover and
+ * Tooltip content to `document.body`, so a Select opened inside a Dialog is a
+ * *sibling* of the dialog portal, not a child of it — the DOM nesting that
+ * would normally settle paint order is gone, and the raw z-index values decide.
+ * While `--z-dropdown` sat at 20 and `--z-modal` at 40, the wiki style Select in
+ * the Add Repository dialog opened behind the dialog overlay. Nothing threw,
+ * nothing logged, and the listbox still took focus, so arrow keys changed the
+ * value under a dropdown the user could not see.
+ *
+ * No render test can catch this: jsdom has no paint and no stacking contexts,
+ * and the wizard's own test renders the Select happily today. The assertion has
+ * to be on the scale itself.
+ */
+
+const CSS = join(__dirname, "../styles/globals.css");
+const UI_SRC = join(__dirname, "../src");
+
+/** Surfaces own a region of the page. */
+const SURFACES = ["--z-base", "--z-elevated", "--z-sidebar", "--z-modal", "--z-command"];
+/** Floating layers are transient and anchored to a control on a surface. */
+const FLOATING = ["--z-dropdown"];
+
+function zTokens(): Map<string, number> {
+ const css = readFileSync(CSS, "utf8");
+ const out = new Map<string, number>();
+ for (const m of css.matchAll(/(--z-[a-z0-9-]+)\s*:\s*(\d+)\s*;/g)) {
+ out.set(m[1]!, Number(m[2]!));
+ }
+ return out;
+}
+
+function z(name: string): number {
+ const value = zTokens().get(name);
+ if (value === undefined) throw new Error(`${name} is not defined in globals.css`);
+ return value;
+}
+
+describe("z-index layering", () => {
+ it("puts every floating layer above every surface", () => {
+ const inverted: string[] = [];
+ for (const float of FLOATING) {
+ for (const surface of SURFACES) {
+ if (z(float) <= z(surface)) {
+ inverted.push(`${float} (${z(float)}) must be above ${surface} (${z(surface)})`);
+ }
+ }
+ }
+ expect(inverted).toEqual([]);
+ });
+
+ it("clears the command palette, which hardcodes calc(var(--z-modal) + 1)", () => {
+ // packages/web/src/components/search/command-palette.tsx does not read
+ // --z-command; it offsets --z-modal directly. A dropdown that only cleared
+ // --z-modal would still open behind the palette.
+ expect(z("--z-dropdown")).toBeGreaterThan(z("--z-modal") + 1);
+ });
+
+ it("keeps toasts above everything, floating layers included", () => {
+ for (const name of [...SURFACES, ...FLOATING]) {
+ expect(z("--z-toast")).toBeGreaterThan(z(name));
+ }
+ });
+
+ it("finds the whole scale, so a broken matcher cannot pass vacuously", () => {
+ const tokens = zTokens();
+ expect(tokens.size).toBe(7);
+ for (const name of [...SURFACES, ...FLOATING, "--z-toast"]) {
+ expect(tokens.has(name)).toBe(true);
+ }
+ });
+
+ /**
+ * The ordering above only means something while the components still read the
+ * tokens this test sorts. If a portalled layer is switched to a bare `z-50`,
+ * the scale can stay perfectly ordered and the bug comes straight back.
+ */
+ it("keeps the portalled layers on --z-dropdown and the dialog on --z-modal", () => {
+ const onDropdown = ["ui/select.tsx", "ui/popover.tsx", "ui/tooltip.tsx"];
+ for (const file of onDropdown) {
+ const text = readFileSync(join(UI_SRC, file), "utf8");
+ expect(text, `${file} should position itself with --z-dropdown`).toContain(
+ "z-[var(--z-dropdown)]",
+ );
+ }
+
+ const dialog = readFileSync(join(UI_SRC, "ui/dialog.tsx"), "utf8");
+ // Overlay and content both, or the listbox clears one and not the other.
+ expect(dialog.match(/z-\[var\(--z-modal\)\]/g) ?? []).toHaveLength(2);
+ });
+
+ /**
+ * The mirror of the test above, and the one the ordering test cannot do on
+ * its own: SURFACES lists the tokens, not the elements wearing them. A panel
+ * that reaches for a FLOATING token inherits its rank, and `--z-dropdown` at
+ * 55 puts that panel above the dialogs and the command palette it should sit
+ * under.
+ *
+ * `graph-canvas-shell.tsx` is why this exists. The rail was pinned to
+ * `--z-dropdown` so it would tie with the tooltips that portal past it —
+ * harmless while `--z-dropdown` was 20 and below `--z-modal`, and an open
+ * rail painting over every dialog under `lg` once it was 55.
+ */
+ it("keeps surfaces off the floating tokens", () => {
+ const surfaces: Array<[string, string]> = [
+ ["graph/graph-canvas-shell.tsx", "--z-sidebar"],
+ ["graph/graph-context-menu.tsx", "--z-modal"],
+ ];
+
+ for (const [file, token] of surfaces) {
+ const text = readFileSync(join(UI_SRC, file), "utf8");
+ expect(text, `${file} should position itself with ${token}`).toContain(
+ `z-[var(${token})]`,
+ );
+ for (const float of FLOATING) {
+ expect(
+ text,
+ `${file} is a surface and must not sit on ${float}, which outranks every surface`,
+ ).not.toContain(`z-[var(${float})]`);
+ }
+ }
+ });
+});
diff --git a/packages/ui/src/graph/graph-canvas-shell.tsx b/packages/ui/src/graph/graph-canvas-shell.tsx
index e57ecebb4..254082f33 100644
--- a/packages/ui/src/graph/graph-canvas-shell.tsx
+++ b/packages/ui/src/graph/graph-canvas-shell.tsx
@@ -111,14 +111,22 @@ export function GraphCanvasShell({
className={cn(
// Bottom sheet under lg so the canvas keeps its height on a
// phone; a real grid column from lg up.
- // `--z-dropdown`, which is the raw `z-20` this used to carry
- // spelled as the token. Deliberately NOT `--z-sidebar`: Radix
- // tooltips and popovers portal to `body` at `--z-dropdown`, so a
- // rail that outranked them would render its own tooltips behind
- // itself. Equal, and later in the DOM, is what makes them land on
- // top. It still clears the canvas chrome at `--z-elevated`, and
- // still yields to the context menu and the help modal.
- "absolute inset-x-0 bottom-0 z-[var(--z-dropdown)] flex max-h-[70%] flex-col overflow-hidden",
+ // `--z-sidebar`: the rail is a surface, and surfaces sit below
+ // every floating layer. It clears the canvas chrome at
+ // `--z-elevated` and yields to the context menu and the help
+ // modal at `--z-modal`.
+ //
+ // This used to be `--z-dropdown`, to tie with the Radix tooltips
+ // and popovers that portal to `body` — a rail that outranked them
+ // would have rendered its own tooltips behind itself, and equal
+ // plus later in the DOM was what put them on top. That tie is no
+ // longer needed: `--z-dropdown` now outranks every surface, so
+ // those tooltips land in front by the scale rather than by DOM
+ // order. Staying on `--z-dropdown` would instead drag this rail
+ // above `--z-modal`, and an open rail would paint over any dialog
+ // under `lg` (above `lg` it is `lg:static` and z-index stops
+ // applying). See `packages/ui/__tests__/z-layering.test.ts`.
+ "absolute inset-x-0 bottom-0 z-[var(--z-sidebar)] flex max-h-[70%] flex-col overflow-hidden",
"rounded-t-xl border-t border-[var(--color-border-default)] bg-[var(--color-bg-surface)] shadow-xl shadow-black/20",
// `h-0 min-h-full`: fill the row without contributing to its
// height, so a tall panel scrolls instead of stretching the canvas.
diff --git a/packages/ui/src/graph/graph-context-menu.tsx b/packages/ui/src/graph/graph-context-menu.tsx
index 9e0f6fa2b..0faf08329 100644
--- a/packages/ui/src/graph/graph-context-menu.tsx
+++ b/packages/ui/src/graph/graph-context-menu.tsx
@@ -28,9 +28,10 @@ export const GraphContextMenu = memo(function GraphContextMenu({
return (
<div
- // `--z-modal`, because this is `fixed` and has to clear the rail
- // (`--z-sidebar`); `--z-dropdown` sits below it and would put the menu
- // behind an open panel.
+ // `--z-modal`, because this is `fixed` and has to clear the rail at
+ // `--z-sidebar`. Not `--z-dropdown`: that is the floating tier, which now
+ // outranks every surface, and this menu should still yield to a dialog
+ // and to the command palette.
className="fixed z-[var(--z-modal)] min-w-[200px] rounded-lg border border-[var(--color-border-default)] bg-[var(--color-bg-overlay)] shadow-xl shadow-black/40 backdrop-blur-md py-1 text-xs"
style={{ left: x, top: y }}
>
diff --git a/packages/ui/styles/globals.css b/packages/ui/styles/globals.css
index cf787b7b5..1312b6831 100644
--- a/packages/ui/styles/globals.css
+++ b/packages/ui/styles/globals.css
@@ -389,12 +389,29 @@
--radius-lg: 10px;
--radius-xl: 14px;
+ /*
+ * Stacking order, low to high. Two groups: *surfaces*, which own a region of
+ * the page, and *floating layers*, which are transient and anchored to a
+ * control that already lives on one of those surfaces.
+ *
+ * Floating layers therefore sit above every surface. Radix portals a Select,
+ * Popover and Tooltip to document.body, so inside a Dialog they are siblings
+ * of the dialog portal rather than children of it, and nothing but z-index
+ * decides which paints on top. With --z-dropdown below --z-modal, the wiki
+ * style Select in the Add Repository dialog opened underneath the dialog's
+ * own overlay.
+ *
+ * --z-command is above --z-modal because the command palette opens over
+ * dialogs; note it currently hardcodes calc(var(--z-modal) + 1) instead of
+ * reading this token, so --z-dropdown has to clear that value too.
+ * Toasts stay above everything, floating layers included.
+ */
--z-base: 0;
--z-elevated: 10;
- --z-dropdown: 20;
--z-sidebar: 30;
--z-modal: 40;
--z-command: 50;
+ --z-dropdown: 55;
--z-toast: 60;
--sidebar-width: 260px;