Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.
C aiderastclaude-codecode-analysiscode-intelligencecodexcursorcypherdeveloper-toolsgemini-cligraph-visualizationkilocodeknowledge-graphmcpmcp-servermodel-context-protocolopencodesqlitetree-sitterwindsurf
/**
* Ein Tooltip, den diese Oberflaeche selbst zeichnet, selbst platziert und
* selbst messen laesst.
*
* ## Warum es ihn gibt
*
* Bis W8b erklaerte sich diese Oberflaeche mit dem `title`-Attribut, 78 Mal.
* Der Browser zeichnet daraus einen Kasten AUSSERHALB des Dokuments, unter dem
* Mauszeiger und ohne Rechteck. Zwei Folgen, und beide sind Fehler:
*
* 1. Er legt sich ueber das, was gerade unter ihm liegt. Im Screenshot des
* Nutzers vom 2026-08-29 lag "76 nodes, 178 edges from /api/layout" ueber
* dem Detail-Regler und ueber den Chips Logic, Calls, Data.
* 2. Keine Messung sieht ihn. Die Ueberlagerungsregel dieses Projekts liest
* `getBoundingClientRect`, und ein nativer Tooltip hat keine. Der Fehler
* war also nicht nur da, er war unsichtbar fuer jeden gruenen Beweislauf.
*
* Dieser Kasten hat beides umgekehrt: er steht im Dokument, er rechnet seine
* Lage (src/ui/tooltip/tooltip-model.ts), und er traegt eine Testmarke, an der
* ein Lauf ihn einzeln oeffnen und vermessen kann.
*
* ## Warum er in den Rumpf portiert wird und nicht neben den Ausloeser
*
* Weil er sonst die Geschwisterordnung seines Ausloesers aendert. Ein Kasten,
* der nur manchmal zwischen zwei Chips steht, ist ein Layout, das beim
* Beruehren zuckt, und CSS-Regeln, die auf Nachbarschaft zeigen, wuerden
* gelegentlich danebengreifen. Im Rumpf liegt er fest positioniert und
* beruehrt die Anordnung von nichts.
*
* ## Die Tastatur ist keine Zugabe
*
* Er oeffnet bei Hover UND bei Fokus, und Escape schliesst ihn. Ein Tooltip,
* den nur die Maus oeffnet, waere fuer die Haelfte dieser Oberflaeche gar
* nicht da: sie ist an der Tastatur entworfen (PLAN Abschnitt 4). Escape haengt
* in der EINFANGENDEN Phase am Fenster, damit er vor den Griffen der grossen
* Flaechen drankommt: wer einen Tooltip offen hat und Escape drueckt, meint
* ihn, und nicht den Bereich dahinter. Die Griffe dahinter pruefen
* `defaultPrevented` und lassen die Taste dann liegen.
*
* ## Der Klick-Griff, und warum ihn der Ausloeser holen muss
*
* Hover und Fokus sind zwei Wege, und auf einem Zeigegeraet ohne Hover ist
* keiner davon einer: wer tippt, hovert nicht, und wer die Maus nicht auf ein
* Zeichen legt, um zu sehen ob etwas passiert, erfaehrt nie, dass dort etwas
* steht. Ein Ausloeser, der nichts anderes tut als diesen Satz zu tragen, ist
* damit unerreichbar, und wenn er ausserdem ein `<button>` ist, verspricht er
* eine Handlung, die es nicht gibt (Befund W10-1, `npm run check:promises`).
*
* Dafuer gibt es {@link HintHold}: ein Klick HAELT den Kasten fest, ein zweiter
* Klick, Escape oder ein Klick daneben laesst ihn los. Der Griff wird aber
* nicht jedem Ausloeser aufgedraengt, sondern nur dem, der ihn nimmt (die
* Funktionsform von `children`). Der Grund ist der Absatz weiter unten an
* `onClick`: an einem Schalter, der etwas TUT, ist der Satz nach dem Druecken
* die Beschreibung von etwas, das schon passiert ist, und meist ausserdem
* falsch. Wuerde ein Klick dort festhalten statt zu schliessen, bliebe genau
* der veraltete Satz stehen, den der Beweislauf aus W9 im Bild gefunden hat.
* Ein Griff fuer die stummen Ausloeser, kein Griff fuer die handelnden: das ist
* EINE Regel an EINER Stelle und gilt fuer alle Hints dieser Oberflaeche.
*
* ## Wo er NICHT hingehoert
*
* Ein Tooltip ist kein Ersatz fuer eine fehlende Beschriftung. Wo ein `title`
* nur den sichtbaren Text wiederholt hat, ist er in W8b ersatzlos entfallen;
* wo eine Flaeche ihren Grund IM FELD sagen muss (die gedimmten Reiter des
* Erklaeren-Bereichs), sagt sie ihn weiterhin dort.
*/
import type { JSX, ReactElement, ReactNode } from 'react';
import { cloneElement, useCallback, useEffect, useId, useLayoutEffect, useRef, useState } from 'react';
import { createPortal } from 'react-dom';
import {
HINT_MAX_WIDTH,
HINT_PROTECTED_SELECTOR,
placeHint,
} from './tooltip-model';
import type { HintPlacement, HintRect } from './tooltip-model';
/**
* Der Griff, mit dem ein Ausloeser seinen Kasten festhaelt.
*
* Er wird der Funktionsform von `children` uebergeben, damit der Klick-Griff
* dort steht, wo er hingehoert: am Element, das ihn traegt. Das ist auch die
* Form, in der ein Leser des Quelltextes (und tools/promise-scan.mjs) sieht,
* dass dieser Knopf auf einen Klick antwortet.
*/
export interface HintHold {
/** Ob der Kasten gerade festgehalten wird. */
held: boolean;
/** Festhalten, oder loslassen, wenn er schon haengt. */
toggle: () => void;
}
export interface HintProps {
/**
* Der Satz. Leer oder fehlend heisst: kein Tooltip, und der Ausloeser wird
* unveraendert durchgereicht.
*
* Der Fall ist keine Bequemlichkeit, sondern der Normalfall an mehreren
* Stellen: eine Zeile, die als Chip gezeichnet wird, traegt ihren Ort im
* Tooltip, und dieselbe Zeile als volle Zeile traegt ihn sichtbar daneben.
*/
text?: string | undefined;
/** Woran ein Beweislauf diesen Tooltip wiedererkennt. */
name: string;
/**
* Genau ein Element: der Ausloeser.
*
* Als Funktion geschrieben bekommt er den {@link HintHold} und bindet den
* Klick selbst. Dann und nur dann haelt ein Klick den Kasten fest, statt
* ihn zu schliessen.
*/
children: ReactElement | ((hold: HintHold) => ReactElement);
}
/*
* Ob ein Element ueberhaupt gezeichnet ist.
*
* Handtest 2026-10-04 (G3): der Inhalt eines zugeklappten `<details>` ist
* nicht zu sehen, behaelt im Browser aber einen Kasten (die Menues "Path to…"
* und "Edge types" der Galaxie mit ihren Feldern). Als geschuetzt gezaehlt,
* schoben sie den Kasten von "Expand +1" vom Platz unter dem Knopf in den Kopf
* der Seite. `checkVisibility` sagt es im Browser fuer jeden Grund; die Regel
* fuer `<details>` gilt auch dort, wo es die Methode nicht gibt.
*/
function rendered(node: Element): boolean {
const closed = node.closest('details:not([open])');
if (closed !== null && !(closed.querySelector(':scope > summary')?.contains(node) ?? false)) {
return false;
}
return typeof node.checkVisibility !== 'function' || node.checkVisibility();
}
/** Die Rechtecke, die an dieser Stelle nicht verdeckt werden duerfen. */
function protectedRects(anchor: Element): HintRect[] {
const out: HintRect[] = [];
for (const node of document.querySelectorAll(HINT_PROTECTED_SELECTOR)) {
if (node === anchor || !rendered(node)) {
continue;
}
const style = window.getComputedStyle(node);
if (style.display === 'none' || style.visibility === 'hidden') {
continue;
}
const rect = node.getBoundingClientRect();
if (rect.width <= 0 || rect.height <= 0) {
continue;
}
out.push({ x: rect.left, y: rect.top, width: rect.width, height: rect.height });
}
return out;
}
/** Zwei Rueckrufe hintereinander, wo der Ausloeser schon einen hatte. */
function both<T>(first: ((value: T) => void) | undefined, second: (value: T) => void) {
return (value: T): void => {
first?.(value);
second(value);
};
}
export default function Hint(props: HintProps): JSX.Element {
const text = (props.text ?? '').replace(/\s+/g, ' ').trim();
const id = `atlas-hint-${useId().replace(/:/g, '')}`;
/*
* Zwei Gruende, offen zu stehen, und sie muessen getrennt bleiben.
*
* `near` ist der Zeiger oder der Fokus: er kommt und geht, ohne dass jemand
* etwas entschieden hat. `held` ist eine Entscheidung des Lesers, und die
* ueberlebt es, dass der Zeiger weiterzieht. Ein einziges `open` koennte
* das nicht auseinanderhalten: das Verlassen des Ausloesers wuerde eine
* Entscheidung zuruecknehmen, die niemand zurueckgenommen hat.
*/
const [near, setNear] = useState(false);
const [held, setHeld] = useState(false);
const open = near || held;
const [placed, setPlaced] = useState<HintPlacement | null>(null);
const anchor = useRef<HTMLElement | null>(null);
const box = useRef<HTMLSpanElement | null>(null);
/** Zu, aus beiden Gruenden. Alles, was schliesst, schliesst ganz. */
const release = useCallback(() => {
setNear(false);
setHeld(false);
}, []);
/*
* Der Griff, und er ist leer, wenn es nichts zu sagen gibt: ein Ausloeser
* ohne Satz reicht sein Element unveraendert durch, und ein Klick darf dann
* auch keinen Zustand anfassen, den niemand sehen kann.
*/
const hold: HintHold = {
held: text.length > 0 && held,
toggle: () => {
if (text.length === 0) {
return;
}
if (held) {
/*
* Der zweite Klick nimmt auch den Zeiger aus der Rechnung. Sonst
* stuende der Kasten weiter da, weil die Maus nach dem Klick
* liegen bleibt, und ein Leser, der ihn eben weggeklickt hat,
* saehe keinen Unterschied.
*/
release();
return;
}
setHeld(true);
},
};
/*
* Erst zeichnen, dann messen, dann stellen.
*
* Die Lage haengt an der Groesse des Kastens, und die Groesse haengt am
* Text und an der Breite, die der Umbruch daraus macht. Sie zu schaetzen
* hiesse, an zwei Stellen zu wissen, wie diese Schrift bricht. Der Kasten
* steht darum im ersten Bild unsichtbar da (`visibility: hidden`, also auch
* kein Kandidat der Lesbarkeitsmessung) und im zweiten an seinem Platz.
*/
useLayoutEffect(() => {
if (!open) {
setPlaced(null);
return;
}
const trigger = anchor.current;
const node = box.current;
if (trigger === null || node === null) {
return;
}
const rect = trigger.getBoundingClientRect();
setPlaced(placeHint({
anchor: { x: rect.left, y: rect.top, width: rect.width, height: rect.height },
size: { width: node.offsetWidth, height: node.offsetHeight },
viewport: { width: window.innerWidth, height: window.innerHeight },
protect: protectedRects(trigger),
}));
}, [open, text]);
// Escape, in der einfangenden Phase. Warum, steht im Kopf.
useEffect(() => {
if (!open) {
return;
}
const onKey = (event: globalThis.KeyboardEvent): void => {
if (event.key !== 'Escape') {
return;
}
event.preventDefault();
release();
};
window.addEventListener('keydown', onKey, true);
return () => window.removeEventListener('keydown', onKey, true);
}, [open, release]);
/*
* Ein Klick daneben laesst den Kasten los.
*
* Escape und der zweite Klick sind die beiden Wege, die der Contract nennt,
* aber sie setzen beide voraus, dass der Leser an den Ausloeser
* zurueckfindet. Wer stattdessen einfach weiterarbeitet, meint damit
* dasselbe. Ohne diese Zeile bliebe ein festgehaltener Kasten ueber der
* Stelle stehen, an der es gerade weitergeht, und das ist genau der Fehler,
* gegen den dieses ganze Modul geschrieben ist.
*
* `pointerdown` und nicht `click`, damit er weg ist, bevor die Flaeche
* darunter antwortet, und in der einfangenden Phase aus demselben Grund wie
* Escape.
*/
useEffect(() => {
if (!held) {
return;
}
const onDown = (event: Event): void => {
const trigger = anchor.current;
const target = event.target;
if (trigger !== null && target instanceof Node && trigger.contains(target)) {
return;
}
release();
};
window.addEventListener('pointerdown', onDown, true);
return () => window.removeEventListener('pointerdown', onDown, true);
}, [held, release]);
/*
* Die Funktionsform gibt dem Ausloeser den Griff; die Elementform ist die
* alte und bleibt es. `bound` merkt sich, welche es war, denn davon haengt
* unten ab, was ein Klick bedeutet.
*/
const bound = typeof props.children === 'function';
const child = bound
? (props.children as (value: HintHold) => ReactElement)(hold)
: (props.children as ReactElement);
if (text.length === 0) {
return child;
}
const childProps = child.props as Record<string, unknown>;
const trigger = cloneElement(child, {
'aria-describedby': open ? id : undefined,
'data-hint': text,
'data-hint-name': props.name,
'data-hint-open': open,
/* Getrennt gemeldet, weil es zwei verschiedene Zustaende sind: offen, weil
* jemand hinsieht, und offen, weil jemand ihn festgehalten hat. Ein
* Beweislauf, der nur `data-hint-open` liest, koennte den zweiten nicht
* vom ersten unterscheiden. */
'data-hint-held': held,
ref: (node: HTMLElement | null) => {
anchor.current = node;
const given = (child as unknown as { ref?: unknown }).ref;
if (typeof given === 'function') {
(given as (value: HTMLElement | null) => void)(node);
} else if (given !== null && typeof given === 'object') {
(given as { current: HTMLElement | null }).current = node;
}
},
onMouseEnter: both(childProps.onMouseEnter as ((value: unknown) => void) | undefined, () => setNear(true)),
onMouseLeave: both(childProps.onMouseLeave as ((value: unknown) => void) | undefined, () => setNear(false)),
onFocus: both(childProps.onFocus as ((value: unknown) => void) | undefined, () => setNear(true)),
/*
* Der Fokus geht, der Kasten geht mit, auch der festgehaltene. Er haengt
* an seinem Ausloeser; wer weitertabbt, hat ihn verlassen.
*/
onBlur: both(childProps.onBlur as ((value: unknown) => void) | undefined, release),
/*
* Ein Klick schliesst ihn, und das ist keine Bequemlichkeit.
*
* Ein Tooltip sagt, was ein Knopf TUN WIRD. Ist er gedrueckt, ist der
* Satz von vorhin die Beschreibung einer Handlung, die schon passiert
* ist, und an den meisten Schaltern dieser Oberflaeche ausserdem
* falsch: "hide the CALLS edges" steht dann ueber einem Knopf, der sie
* gerade wieder einblenden wuerde. Der Zeiger bleibt nach einem Klick
* liegen, `mouseover` feuert kein zweites Mal, und der veraltete Satz
* stuende bis zur naechsten Mausbewegung da.
*
* Der Beweislauf von W9 hat genau das aufgedeckt: er klickt eine
* Kantenart aus, laesst den Zeiger dort und nimmt ein Bild der Szene
* auf. Der offene Kasten lag im Bild, und die Differenzmessung, die
* daraus die Farbe einer Kante rechnet, sah eine Flaeche, die keine
* Kante war.
*
* Wer den Griff aus {@link HintHold} selbst gebunden hat, bekommt das
* nicht dazu: sein Klick IST die Entscheidung ueber den Kasten, und ein
* Schliessen dahinter wuerde sie sofort wieder aufheben.
*/
onClick: bound
? (childProps.onClick as ((value: unknown) => void) | undefined)
: both(childProps.onClick as ((value: unknown) => void) | undefined, release),
} as Record<string, unknown>);
const overlay: ReactNode = open ? (
<span
className="atlas-hint"
data-testid="atlas-hint"
data-hint-for={props.name}
data-side={placed?.side ?? 'below'}
data-covered={placed?.covered ?? -1}
id={id}
role="tooltip"
ref={box}
style={{
position: 'fixed',
maxWidth: `${HINT_MAX_WIDTH}px`,
left: `${placed?.x ?? 0}px`,
top: `${placed?.y ?? 0}px`,
visibility: placed === null ? 'hidden' : 'visible',
}}
>
{text}
</span>
) : null;
return (
<>
{trigger}
{overlay !== null && typeof document !== 'undefined'
? createPortal(overlay, document.body)
: null}
</>
);
}