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";
/**
* One way to print a repository path. The file name is what a reader
* recognises, so no mode ever cuts it; the directory gives way first.
*
* - `name-first` (lists, tables): name, then the dim directory, which clips
* in the middle so its first and last folders stay.
* - `distinguishing` (compact sets of siblings): the shortest suffix that
* tells the set apart, from {@link disambiguateBasenames} computed once by
* the caller and passed as `labels`.
* - `full` (drawers, headers): every segment, wrapping only after a slash.
* - `middle-ellipsis` (one-line inline mentions): the path in reading order,
* clipped in the middle by the box width, never by a character count.
*
* Abbreviated modes keep the whole path (and `:line`) as the accessible name
* and in a tooltip that opens on hover and on keyboard focus of the link,
* button or row that holds it. Strings are English props so
* every host app can translate them.
*/
import * as React from "react";
import { useCallback, useEffect, useRef, useState } from "react";
import { Check, Copy } from "lucide-react";
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "../ui/tooltip";
import { cn } from "../lib/cn";
import { foldPackagePrefix, pathWithLine, splitDirTail, splitPath } from "../lib/path-parts";
const TOOLTIP_DELAY_MS = 300;
export type FilePathMode = "name-first" | "distinguishing" | "full" | "middle-ellipsis";
export interface FilePathProps {
path: string;
mode?: FilePathMode;
/** A line (`42`) or range (`12-40`) printed after the name. */
line?: number | string | null | undefined;
/** `distinguishing` only: labels from `disambiguateBasenames(siblings)`, computed once per set. */
labels?: ReadonlyMap<string, string> | undefined;
/** Print `packages/<x>/src/` as an `<x>` chip and drop a namespace that repeats it. Display only. */
fold?: boolean;
/** A copy-path button beside the path. Not inside a link or button: it is a button itself. */
copyable?: boolean;
/** The file name in the link colour, for a path that is a link. */
accent?: boolean;
className?: string;
copyLabel?: string;
copiedLabel?: string;
}
/** A slash-separated string that may wrap only after its slashes. `<wbr>`, so copying stays clean. */
export function SlashBreaks({ text }: { text: string }) {
const segments = text.split("/");
return (
<>
{segments.map((segment, i) => (
<React.Fragment key={i}>
{segment}
{i < segments.length - 1 ? (
<>
/<wbr />
</>
) : null}
</React.Fragment>
))}
</>
);
}
const DIM = "text-[var(--color-text-tertiary)]";
const ACCENT = "text-[var(--color-accent-primary)]";
// Elements that take focus for the path. Not any `[tabindex]`: a dialog's
// `tabindex="-1"` would open every tooltip in a drawer at once.
const HOST = 'a[href],button,summary,[role=option],[role=row],[role=menuitem],[tabindex="0"]';
function PackageChip({ pkg }: { pkg: string }) {
return (
<span className={cn("shrink-0 rounded-sm bg-[var(--color-bg-inset)] px-1 text-[10px] leading-4", DIM)}>
{pkg}
</span>
);
}
function LineSuffix({ line }: { line: number | string | null | undefined }) {
if (line == null || line === "") return null;
return <span className={cn("tabular-nums", DIM)}>:{line}</span>;
}
/** A directory that clips in the middle: the head gives way, the last folder stays. */
function DirClip({ dir, trailingSlash = false }: { dir: string; trailingSlash?: boolean }) {
const { head, tail } = splitDirTail(dir);
const end = trailingSlash ? "/" : "";
return (
<>
{head ? <span className={cn("min-w-0 truncate", DIM)}>{head}/</span> : null}
<span className={cn("min-w-0 shrink-[0.01] truncate", DIM)}>
{tail}
{end}
</span>
</>
);
}
interface PieceProps {
dir: string;
name: string;
chip: React.ReactNode;
line: FilePathProps["line"];
nameClass: string | undefined;
}
/** Every segment, wrapping only after a slash; the name at reading weight. */
function FullPieces({ dir, name, chip, line, nameClass }: PieceProps) {
return (
<span className="[word-break:normal] [overflow-wrap:break-word]">
{chip ? <span className="mr-1 inline-block">{chip}</span> : null}
{dir ? (
<span className={DIM}>
<SlashBreaks text={`${dir}/`} />
</span>
) : null}
<span className={cn("font-medium", nameClass)}>{name}</span>
<LineSuffix line={line} />
</span>
);
}
/**
* The file name in `name-first`: wider than its column, it wraps rather than
* losing characters. `break-word` keeps its min-content width, so a table
* column is not squeezed to one character.
*/
const NAME_CLS = "max-w-full shrink-0 whitespace-normal [overflow-wrap:break-word]";
/** The name first, then the package chip and a directory that clips. */
function NameFirstPieces({ dir, name, chip, line, nameClass }: PieceProps) {
return (
<span className="flex min-w-0 items-baseline gap-1.5 whitespace-nowrap">
<span className={cn(NAME_CLS, nameClass)}>
{name}
<LineSuffix line={line} />
</span>
{chip}
{dir ? (
<span className="flex min-w-0">
<DirClip dir={dir} />
</span>
) : null}
</span>
);
}
/** Path order on one line: distinguishing labels and middle-ellipsis mentions. */
function InlinePieces({ dir, name, chip, line, nameClass }: PieceProps) {
return (
<span className="flex min-w-0 items-baseline whitespace-nowrap">
{chip ? <span className="mr-1 flex shrink-0">{chip}</span> : null}
{dir ? <DirClip dir={dir} trailingSlash /> : null}
{/* One line: the name stays whole and unwrapped; the directory clips first. */}
<span className={cn("shrink-0 whitespace-nowrap", nameClass)}>{name}</span>
<LineSuffix line={line} />
</span>
);
}
const PIECES: Record<FilePathMode, (props: PieceProps) => React.ReactElement> = {
full: FullPieces,
"name-first": NameFirstPieces,
distinguishing: InlinePieces,
"middle-ellipsis": InlinePieces,
};
/** What the mode prints: a distinguishing label, or the (optionally folded) path. */
function displayed(path: string, mode: FilePathMode, labels: FilePathProps["labels"], fold: boolean) {
if (mode === "distinguishing") return { pkg: null, rest: labels?.get(path) ?? splitPath(path).name };
return fold ? foldPackagePrefix(path) : { pkg: null, rest: path };
}
function Visual({
path,
mode,
line,
labels,
fold = false,
accent,
}: Required<Pick<FilePathProps, "path" | "mode">> &
Pick<FilePathProps, "line" | "labels" | "fold" | "accent">) {
const { pkg, rest } = displayed(path, mode, labels, fold);
const Pieces = PIECES[mode];
return (
<Pieces
{...splitPath(rest)}
chip={pkg ? <PackageChip pkg={pkg} /> : null}
line={line}
nameClass={accent ? ACCENT : undefined}
/>
);
}
/** True for keyboard focus; an engine without `:focus-visible` counts as keyboard. */
function isKeyboardFocus(el: HTMLElement): boolean {
try {
return el.matches(":focus-visible");
} catch {
return true;
}
}
/**
* Opens the tooltip while the link or row holding the path has keyboard focus.
* A path with no such host stays out of the tab order, so a plain list does
* not gain a tab stop per row; its full path is still the accessible name.
* Imperative, so a long list mounts without a re-render per row.
*/
function useHostFocus(
ref: React.RefObject<HTMLElement | null>,
setOpen: (open: boolean) => void,
active: boolean,
) {
useEffect(() => {
const el = ref.current;
if (!active || !el) return;
const host = el.parentElement?.closest<HTMLElement>(HOST);
if (!host) return;
const show = () => {
if (isKeyboardFocus(host)) setOpen(true);
};
const hide = () => setOpen(false);
host.addEventListener("focus", show);
host.addEventListener("blur", hide);
return () => {
host.removeEventListener("focus", show);
host.removeEventListener("blur", hide);
};
}, [ref, setOpen, active]);
}
function CopyPathButton({ text, label, copiedLabel }: { text: string; label: string; copiedLabel: string }) {
const [copied, setCopied] = useState(false);
const copy = async () => {
try {
await navigator.clipboard.writeText(text);
setCopied(true);
window.setTimeout(() => setCopied(false), 1600);
} catch {
/* clipboard blocked: the path stays selectable */
}
};
return (
<button
type="button"
onClick={(e) => {
e.stopPropagation();
void copy();
}}
aria-label={copied ? copiedLabel : label}
className={cn(
"ml-1 inline-flex shrink-0 items-center self-center rounded-sm hover:text-[var(--color-text-primary)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-focus-ring)]",
DIM,
)}
>
{copied ? <Check className="h-3 w-3" aria-hidden /> : <Copy className="h-3 w-3" aria-hidden />}
</button>
);
}
export function FilePath({
path,
mode = "name-first",
line,
labels,
fold = false,
copyable = false,
accent = false,
className,
copyLabel = "Copy path",
copiedLabel = "Copied",
}: FilePathProps) {
const ref = useRef<HTMLSpanElement>(null);
const [open, setOpen] = useState(false);
// The tooltip machinery mounts on first hover or focus, so a list of a
// thousand paths mounts no Radix provider, root or listener per row, and
// the path still works in hosts that mount no ambient TooltipProvider.
const [armed, setArmed] = useState(false);
const reveal = useCallback((next: boolean) => {
if (next) setArmed(true);
setOpen(next);
}, []);
// The hover that arms happens before the trigger exists, so Radix never
// sees it; that hover opens the tooltip itself, after the same delay.
const hoverTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
const cancelHover = useCallback(() => clearTimeout(hoverTimer.current), []);
const armOnHover = useCallback(() => {
setArmed(true);
hoverTimer.current = setTimeout(() => setOpen(true), TOOLTIP_DELAY_MS);
}, []);
useEffect(() => cancelHover, [cancelHover]);
const full = pathWithLine(path, line);
// `full` shows every character in reading order, and a bare top-level
// file is already its whole path: neither needs a second, hidden copy.
const abbreviated = mode !== "full" && (path.includes("/") || full !== path);
useHostFocus(ref, reveal, abbreviated);
const visual = (
<Visual path={path} mode={mode} line={line} labels={labels} fold={fold} accent={accent} />
);
const copy = copyable ? <CopyPathButton text={path} label={copyLabel} copiedLabel={copiedLabel} /> : null;
if (!abbreviated) {
return (
<span
data-path={path}
className={cn("min-w-0 font-mono text-xs", mode === "full" ? "inline" : "inline-flex max-w-full", className)}
>
{visual}
{copy}
</span>
);
}
const trigger = (
<span
ref={ref}
className="flex min-w-0 max-w-full"
onPointerEnter={armed ? undefined : armOnHover}
>
<span className="sr-only">{full}</span>
<span aria-hidden className="flex min-w-0">
{visual}
</span>
</span>
);
return (
// The leave is caught here, on a node arming does not remount, so a pointer
// that leaves while the trigger moves into the tooltip still cancels it.
<span
data-path={path}
className={cn("inline-flex min-w-0 max-w-full items-baseline font-mono text-xs", className)}
onPointerLeave={cancelHover}
>
{armed ? (
<TooltipProvider delayDuration={TOOLTIP_DELAY_MS}>
<Tooltip open={open} onOpenChange={setOpen}>
<TooltipTrigger asChild>{trigger}</TooltipTrigger>
<TooltipContent className="max-w-[min(36rem,90vw)] font-mono [overflow-wrap:anywhere]">{full}</TooltipContent>
</Tooltip>
</TooltipProvider>
) : (
trigger
)}
{copy}
</span>
);
}