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.

6.6 KB
Raw Blame
"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>
  );
}