Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
"use client";
import * as React from "react";
import { cn } from "../lib/cn";
export interface GraphCanvasShellProps {
/** "You are here", above the title. Present only once the canvas is showing
* something narrower than the whole scope, so it never adds a permanent row. */
breadcrumb?: React.ReactNode | undefined;
/** Optional one-line title rendered above the canvas (no second header band). */
title?: string | undefined;
/** Optional one-line description under the title. */
description?: string | undefined;
/** Right-aligned slot in the title row. Scope controls and the toolbar live
* here rather than floating over the diagram. */
titleActions?: React.ReactNode | undefined;
/** A full-width banner slot above the canvas (e.g. truncation notice). */
banner?: React.ReactNode | undefined;
/** The canvas itself (Sigma / ReactFlow host). Fills the remaining height. */
children: React.ReactNode;
/**
* Inspector content. A grid peer of the canvas from `lg` up, so a panel can
* never land on the map; below `lg` it becomes a bottom sheet over the canvas
* rather than starving it of height. Render nothing when there is no
* selection to explain and the canvas takes the full width.
*/
rail?: React.ReactNode | undefined;
/** Legend / key row, rendered as a caption under the canvas. */
footer?: React.ReactNode | undefined;
/**
* Drawn on top of the canvas. Reserved for pointer-bound things: context
* menus, hover cards, modals. Persistent chrome belongs in `titleActions`,
* `footer` or `rail`.
*/
overlay?: React.ReactNode | undefined;
/**
* `page` (default) fills a full-bleed page and pads its rows. `section` sits
* inside a padded page section: rows align with the section's text, and the
* canvas and rail share one hairline frame.
*/
variant?: "page" | "section" | undefined;
className?: string | undefined;
}
/** Row padding and canvas frame per variant. */
const VARIANT = {
page: { pad: "px-4 sm:px-6", frame: "" },
section: { pad: "", frame: "overflow-hidden rounded-lg border border-[var(--color-border-default)] bg-[var(--color-bg-root)]" },
} as const;
/**
* The single canvas container for every graph surface.
*
* Chrome goes around the map, not on it: controls in the title row, key
* underneath, inspector as a grid peer. This mirrors `SystemMap`, the Code
* Health triage view and the Knowledge Graph page, which all converged on the
* same arrangement.
*/
export function GraphCanvasShell({
breadcrumb,
title,
description,
titleActions,
banner,
children,
rail,
footer,
overlay,
variant = "page",
className,
}: GraphCanvasShellProps) {
const { pad, frame } = VARIANT[variant];
return (
<div className={cn("flex h-full flex-col", className)}>
{(breadcrumb || title || description || titleActions) && (
<div className={cn("flex shrink-0 flex-wrap items-start justify-between gap-2 pt-3", pad)}>
<div className="min-w-0 max-w-2xl">
{breadcrumb && <div className="mb-1 min-w-0">{breadcrumb}</div>}
{title && (
<h2 className="text-sm font-semibold text-[var(--color-text-primary)]">
{title}
</h2>
)}
{description && (
<p className="mt-0.5 text-xs text-[var(--color-text-secondary)]">
{description}
</p>
)}
</div>
{titleActions && (
<div className="flex min-w-0 flex-wrap items-center justify-end gap-2">
{titleActions}
</div>
)}
</div>
)}
{banner && <div className={cn("shrink-0 pt-3", pad)}>{banner}</div>}
<div
className={cn(
"relative mt-3 grid min-h-0 flex-1",
rail ? "lg:grid-cols-[minmax(0,1fr)_340px]" : "grid-cols-1",
frame,
)}
>
{/* A floor, so a tall header or key row cannot squeeze the subject to
nothing; the page scrolls instead.
Below `lg` the rail is a sheet over the bottom 70% of this cell, and
the canvas parks its own zoom/fit controls at `bottom-3`. Opening a
panel therefore buried them. This publishes the sheet's extent as a
variable the canvas chrome reads for its own offset, so the controls
step above the sheet instead of under it. Above `lg` the rail is a
grid peer and there is nothing to clear. */}
<div
className={cn(
"relative min-h-0 overflow-hidden max-lg:min-h-[22rem]",
rail && "max-lg:[--canvas-chrome-bottom:calc(70%+0.75rem)]",
)}
>
{children}
{overlay}
</div>
{rail && (
<aside
className={cn(
// Bottom sheet under lg so the canvas keeps its height on a
// phone; a real grid column from lg up.
// `--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.
"lg:static lg:h-0 lg:min-h-full lg:max-h-none lg:rounded-none lg:border-t-0 lg:border-l lg:shadow-none",
)}
>
{rail}
</aside>
)}
</div>
{footer && <div className={cn("shrink-0 pb-3 pt-2", pad)}>{footer}</div>}
</div>
);
}