Skip to content

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.

fix(ui): keep the root names in the Explore mini-Galaxy apart (K12)

Bernhard Jackiewicz33c3098f680d
diff --git a/graph-ui/src/galaxy/GraphScene.root-markers.test.tsx b/graph-ui/src/galaxy/GraphScene.root-markers.test.tsx
new file mode 100644
index 000000000..778c44f0b
--- /dev/null
+++ b/graph-ui/src/galaxy/GraphScene.root-markers.test.tsx
@@ -0,0 +1,65 @@
+// @vitest-environment jsdom
+/*
+ * Handtest K12: im Mini-Galaxy von Explore lagen die Namen der markierten
+ * Wurzeln aufeinander. Die Namen nehmen jetzt freie Plaetze um ihre Ringe
+ * (marker-names.ts); hier steht, dass die Szene sie dorthin setzt.
+ */
+import { act, type ReactNode } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+import { PerspectiveCamera } from 'three';
+import { RootMarkers } from './GraphScene';
+import type { GraphNode } from './types';
+
+const fiber = vi.hoisted(() => ({ frames: [] as ((state: unknown, delta: number) => void)[] }));
+let scene: { camera: PerspectiveCamera; gl: { domElement: HTMLCanvasElement }; size: { width: number; height: number } };
+vi.mock('@react-three/fiber', async importOriginal => ({
+ ...await importOriginal<typeof import('@react-three/fiber')>(),
+ useFrame: (callback: (state: unknown, delta: number) => void) => { fiber.frames.push(callback); },
+ useThree: (select?: (state: unknown) => unknown) => (select ? select(scene) : scene),
+}));
+vi.mock('@react-three/drei', async importOriginal => ({
+ ...await importOriginal<typeof import('@react-three/drei')>(),
+ Html: ({ children }: { children: ReactNode }) => <div data-testid="html">{children}</div>,
+}));
+
+let host: HTMLDivElement, root: Root;
+beforeEach(() => {
+ (globalThis as unknown as Record<string, unknown>).IS_REACT_ACT_ENVIRONMENT = true;
+ const canvas = document.createElement('canvas');
+ canvas.getBoundingClientRect = () => ({ left: 0, top: 0, right: 800, bottom: 600, width: 800, height: 600, x: 0, y: 0, toJSON: () => ({}) });
+ scene = { camera: new PerspectiveCamera(50, 800 / 600, 0.1, 100000), gl: { domElement: canvas }, size: { width: 800, height: 600 } };
+ scene.camera.position.set(0, 0, 800); scene.camera.lookAt(0, 0, 0); scene.camera.updateMatrixWorld(); scene.camera.updateProjectionMatrix();
+ fiber.frames = [];
+ // jsdom lays nothing out: every name is 90 x 18 px.
+ Object.defineProperty(HTMLElement.prototype, 'offsetWidth', { configurable: true, get() { return (this as HTMLElement).tagName === 'B' ? 90 : 0; } });
+ Object.defineProperty(HTMLElement.prototype, 'offsetHeight', { configurable: true, get() { return (this as HTMLElement).tagName === 'B' ? 18 : 0; } });
+ host = document.createElement('div'); document.body.append(host); root = createRoot(host);
+});
+afterEach(() => {
+ act(() => root.unmount()); host.remove();
+ delete (HTMLElement.prototype as unknown as Record<string, unknown>).offsetWidth;
+ delete (HTMLElement.prototype as unknown as Record<string, unknown>).offsetHeight;
+});
+const node = (id: number, x: number, y: number): GraphNode => ({ id, x, y, z: 0, name: `name ${id}`, label: 'Variable', size: 3, color: '#abcdef' });
+const runFrames = (count: number) => act(() => { for (let i = 0; i < count; i++) for (const frame of fiber.frames) frame({}, 1 / 60); });
+
+it('K12: root names that would lie on each other take different places, a lone one stays under its ring', () => {
+ act(() => root.render(<RootMarkers nodes={[node(1, 0, 0)]} />));
+ runFrames(6);
+ expect(host.querySelector('[data-testid="atlas-galaxy-root-marker"]')?.getAttribute('data-name-slot')).toBe('below');
+
+ act(() => root.render(<RootMarkers nodes={[node(1, 0, 0), node(2, 2, 1), node(3, -2, -1)]} />));
+ runFrames(6);
+ const markers = [...host.querySelectorAll<HTMLElement>('[data-testid="atlas-galaxy-root-marker"]')];
+ const slots = markers.map(marker => marker.getAttribute('data-name-slot'));
+ expect(slots[0]).toBe('below');
+ // No two shown names share a place; a name without a free place is hidden, never laid over another.
+ const shown = slots.filter(slot => slot !== 'hidden');
+ expect(new Set(shown).size).toBe(shown.length);
+ expect(shown.length).toBeGreaterThanOrEqual(2);
+ for (const marker of markers) {
+ const name = marker.querySelector('b')!;
+ expect(name.style.visibility).toBe(marker.getAttribute('data-name-slot') === 'hidden' ? 'hidden' : '');
+ }
+});
diff --git a/graph-ui/src/galaxy/GraphScene.tsx b/graph-ui/src/galaxy/GraphScene.tsx
index 61a72b0a8..6c7d39105 100644
--- a/graph-ui/src/galaxy/GraphScene.tsx
+++ b/graph-ui/src/galaxy/GraphScene.tsx
@@ -103,6 +103,10 @@
* Knoten (`PathFrame`, Rechnung in src/galaxy/path-frame.ts), mit Rand und
* neben der Schrittliste. Die Knoten des Pfades bekommen ihren Namen von der
* Pfadebene; die Namensebene der Szene zeichnet fuer sie keinen zweiten.
+ * 20. Neu (Handtest K12): die Namen der Wurzelmarken suchen sich freie Plaetze
+ * um ihre Ringe (src/galaxy/marker-names.ts), statt bei mehreren Wurzeln
+ * aufeinander zu liegen; ein Name ohne freien Platz wird ausgeblendet. Eine
+ * einzelne Wurzel behaelt ihren Namen unter dem Ring.
*/
import { useState, useRef, useEffect, useCallback, useMemo } from 'react';
@@ -119,6 +123,7 @@ import { NodeLabels } from './NodeLabels';
import { ScreenNodeSeparation } from './ScreenNodeSeparation';
import { PathLayer, pathNodeIds, type ScenePath } from './PathLayer';
import { pathFrame } from './path-frame';
+import { markerNameRect, placeMarkerNames, type MarkerName } from './marker-names';
import type { LabelBox } from './NodeLabels';
import { FRAME_MIN_DISTANCE, containShift, fitCamera, flatBounds, frameDistance, orthographicZoom } from './camera-frame';
import type { CameraFit, FrameBox } from './camera-frame';
@@ -427,12 +432,61 @@ export function FitContainment({
*/
export const ROOT_MARKER_LIMIT = 12;
-function RootMarkers({ nodes }: { nodes: readonly GraphNode[] }): JSX.Element {
+const PLACE_NAMES_EVERY_FRAMES = 3;
+
+/*
+ * Handtest K12: mehrere Wurzeln nah beieinander (die Definitionen einer Datei
+ * im Mini-Galaxy von Explore) legten ihre Namen aufeinander. Alle paar Bilder
+ * bekommt jeder Name einen freien Platz um seinen Ring (marker-names.ts); der
+ * Platz steht als `data-name-slot` an der Marke, ein Name ohne Platz ist
+ * `hidden`. Gemessen wird jeder Name einmal, wie die Schilder der Hierarchie.
+ */
+export function RootMarkers({ nodes }: { nodes: readonly GraphNode[] }): JSX.Element {
+ const markers = useRef(new Map<number, HTMLSpanElement>());
+ const sizes = useRef(new Map<string, { width: number; height: number }>());
+ const placedNames = useRef(new Map<number, string>());
+ const camera = useThree((state) => state.camera);
+ const gl = useThree((state) => state.gl);
+ const tick = useRef(0);
+ const point = useMemo(() => new THREE.Vector3(), []);
+ useFrame(() => {
+ tick.current = (tick.current + 1) % PLACE_NAMES_EVERY_FRAMES;
+ if (tick.current !== 0) return;
+ const box = gl.domElement.getBoundingClientRect();
+ const wanted: MarkerName[] = [];
+ for (const node of nodes) {
+ const name = markers.current.get(node.id)?.querySelector('b');
+ if (!name) continue;
+ let size = sizes.current.get(node.name);
+ if (!size && name.offsetWidth > 0) { size = { width: name.offsetWidth, height: name.offsetHeight }; sizes.current.set(node.name, size); }
+ if (!size) continue;
+ point.set(node.x, node.y, node.z).project(camera);
+ if (!(point.z >= -1 && point.z <= 1)) continue;
+ wanted.push({ id: node.id, x: box.left + ((point.x + 1) / 2) * box.width, y: box.top + ((1 - point.y) / 2) * box.height, ...size });
+ }
+ for (const { id, slot, rect } of placeMarkerNames(wanted, { left: box.left, top: box.top, right: box.right, bottom: box.bottom })) {
+ const marker = markers.current.get(id), name = marker?.querySelector('b');
+ if (!marker || !name) continue;
+ const anchor = wanted.find((entry) => entry.id === id)!;
+ // The name sits at its place relative to the ring centre, which is where drei puts the marker.
+ const offset = rect ? { left: Math.round(rect.left - anchor.x), top: Math.round(rect.top - anchor.y) } : undefined;
+ const standard = rect ? markerNameRect(anchor, 'below') : undefined;
+ const plain = slot === 'below' && rect && standard && Math.abs(rect.left - standard.left) < 0.5;
+ const place = `${slot}:${offset?.left ?? ''}:${offset?.top ?? ''}`;
+ if (placedNames.current.get(id) === place) continue;
+ placedNames.current.set(id, place);
+ marker.dataset.nameSlot = slot;
+ name.style.visibility = slot === 'hidden' ? 'hidden' : '';
+ if (!offset || plain) { name.style.left = ''; name.style.top = ''; name.style.transform = ''; continue; }
+ name.style.left = `${offset.left}px`; name.style.top = `${offset.top}px`; name.style.transform = 'none';
+ }
+ });
return (
<>
{nodes.map((node) => (
<Html key={node.id} position={[node.x, node.y, node.z]} zIndexRange={[10, 0]} style={{ pointerEvents: 'none' }}>
- <span className="atlas-galaxy-root-marker" data-testid="atlas-galaxy-root-marker" data-qn={node.qualified_name ?? node.name}>
+ <span className="atlas-galaxy-root-marker" data-testid="atlas-galaxy-root-marker" data-qn={node.qualified_name ?? node.name}
+ ref={(element) => { if (element) markers.current.set(node.id, element); else markers.current.delete(node.id); }}>
<i aria-hidden="true" />
<b>{node.name}</b>
</span>
diff --git a/graph-ui/src/galaxy/marker-names.test.ts b/graph-ui/src/galaxy/marker-names.test.ts
new file mode 100644
index 000000000..52584ccec
--- /dev/null
+++ b/graph-ui/src/galaxy/marker-names.test.ts
@@ -0,0 +1,64 @@
+import { expect, it } from 'vitest';
+import { MARKER_RING_RADIUS, placeMarkerNames, type MarkerName } from './marker-names';
+import type { ScreenRect } from './path-frame';
+
+const hit = (a: ScreenRect, b: ScreenRect) => !(a.right <= b.left || b.right <= a.left || a.bottom <= b.top || b.bottom <= a.top);
+
+it('keeps a lone root name under its ring, where the stylesheet puts it', () => {
+ const [only] = placeMarkerNames([{ id: 1, x: 400, y: 300, width: 80, height: 19 }], { left: 0, top: 0, right: 800, bottom: 600 });
+ expect(only).toMatchObject({ id: 1, slot: 'below' });
+ expect(only!.rect).toEqual({ left: 360, right: 440, top: 300 + MARKER_RING_RADIUS + 4, bottom: 300 + MARKER_RING_RADIUS + 4 + 19 });
+});
+
+/*
+ * Hand test K12: in Explore the mini-Galaxy of
+ * .github/workflows/new_contributor_pr.yml marks six definitions as roots,
+ * and their names lay on each other ("permissions", "new_contributor_pr.yml",
+ * ".github/workflows/new_contributor_pr.yml", "jobs"). The anchors and sizes
+ * are the ones measured in that panel (419 x 186 px at 1600 px with the chat open).
+ */
+it('gives clustered root names free places around their rings inside the canvas, and no two names overlap', () => {
+ const canvas = { left: 1181, top: 787, right: 1600, bottom: 973 };
+ const names: MarkerName[] = [
+ { id: 1, x: 1444.4, y: 879.3, width: 261.9, height: 18.8 }, // .github/workflows/new_contributor_pr.yml
+ { id: 2, x: 1382.1, y: 909.5, width: 36.9, height: 18.8 }, // jobs
+ { id: 3, x: 1378.8, y: 872.9, width: 44.3, height: 18.8 }, // name
+ { id: 4, x: 1377.0, y: 874.2, width: 152.0, height: 18.8 }, // new_contributor_pr.yml
+ { id: 5, x: 1362.1, y: 861.5, width: 26.7, height: 18.8 }, // on
+ { id: 6, x: 1393.9, y: 865.0, width: 83.8, height: 18.8 }, // permissions
+ ];
+ // As drawn before: every name under its own ring.
+ const under = names.map(name => ({ left: name.x - name.width / 2, right: name.x + name.width / 2, top: name.y + MARKER_RING_RADIUS + 4, bottom: name.y + MARKER_RING_RADIUS + 4 + name.height }));
+ expect(under.some((rect, i) => under.some((other, j) => i < j && hit(rect, other)))).toBe(true);
+
+ const placed = placeMarkerNames(names, canvas);
+ const shown = placed.filter(entry => entry.rect !== undefined);
+ for (const [i, entry] of shown.entries()) {
+ for (const other of shown.slice(i + 1)) expect(hit(entry.rect!, other.rect!), `${entry.id} x ${other.id}`).toBe(false);
+ expect(entry.rect!.left).toBeGreaterThanOrEqual(canvas.left);
+ expect(entry.rect!.right).toBeLessThanOrEqual(canvas.right);
+ expect(entry.rect!.top).toBeGreaterThanOrEqual(canvas.top);
+ expect(entry.rect!.bottom).toBeLessThanOrEqual(canvas.bottom);
+ }
+ // The four names of the hand test are all still there.
+ expect(shown.map(entry => entry.id).sort()).toEqual(expect.arrayContaining([1, 2, 4, 6]));
+ // The order is stable: the same input gives the same places.
+ expect(placeMarkerNames(names, canvas)).toEqual(placed);
+});
+
+it('moves a long name under a ring near the edge sideways into the canvas, still spanning its ring', () => {
+ const canvas = { left: 0, top: 0, right: 400, bottom: 300 };
+ const [name] = placeMarkerNames([{ id: 1, x: 360, y: 100, width: 200, height: 18 }], canvas);
+ expect(name!.slot).toBe('below');
+ expect(name!.rect!.right).toBeLessThanOrEqual(400);
+ expect(name!.rect!.left).toBeLessThan(360 - MARKER_RING_RADIUS);
+ // A ring outside the canvas has no name inside it.
+ expect(placeMarkerNames([{ id: 2, x: 520, y: 100, width: 200, height: 18 }], canvas)[0]!.slot).toBe('hidden');
+});
+
+it('drops a name that finds no free place instead of laying it over another', () => {
+ const canvas = { left: 0, top: 0, right: 120, bottom: 80 };
+ const placed = placeMarkerNames([{ id: 1, x: 60, y: 35, width: 110, height: 18 }, { id: 2, x: 62, y: 36, width: 110, height: 18 }], canvas);
+ expect(placed[0]!.rect).toBeDefined();
+ expect(placed[1]!.rect).toBeUndefined();
+});
diff --git a/graph-ui/src/galaxy/marker-names.ts b/graph-ui/src/galaxy/marker-names.ts
new file mode 100644
index 000000000..c413ac035
--- /dev/null
+++ b/graph-ui/src/galaxy/marker-names.ts
@@ -0,0 +1,90 @@
+/*
+ * Die Namen der markierten Wurzeln, ohne dass einer auf dem anderen liegt
+ * (Handtest K12).
+ *
+ * Ein Ausschnitt um eine Datei markiert jede ihrer Definitionen als Wurzel,
+ * und jede Marke trug ihren Namen fest unter dem Ring. Im Mini-Galaxy von
+ * Explore (419 x 186 px bei offenem Chat) lagen so bei
+ * .github/workflows/new_contributor_pr.yml sechs Namen aufeinander:
+ * "permissions", "new_contributor_pr.yml", ".github/workflows/..." und "jobs"
+ * waren nicht mehr zu lesen.
+ *
+ * Dieselbe Regel wie fuer die Schilder an Pfaden und in der Hierarchie
+ * (path-frame.ts, HierarchyEdgeLabels.tsx): ein Name steht an einem freien
+ * Platz oder gar nicht. Die Plaetze liegen um den eigenen Ring, der erste ist
+ * der der Stilvorlage (unter dem Ring), damit eine einzelne Wurzel aussieht
+ * wie bisher. Von den Plaetzen ohne fremden Namen gewinnt der, der am
+ * wenigsten von den fremden Ringen deckt. Ein Name ohne freien Platz wird
+ * ausgeblendet; die Karte beim Ueberfahren des Knotens nennt ihn weiter.
+ */
+import type { ScreenRect } from './path-frame';
+
+/** Der halbe Ring einer Marke (graph-exploration.css: 30 px) und der Abstand des Namens davon (dort `top: 19px`). */
+export const MARKER_RING_RADIUS = 15;
+const NAME_GAP = 4;
+const ROW_GAP = 2;
+
+export type MarkerNameSlot = 'below' | 'above' | 'right' | 'left' | 'below-2' | 'above-2' | 'right-up' | 'right-down' | 'left-up' | 'left-down';
+
+/** Eine Marke: die Mitte ihres Rings auf dem Schirm und die Groesse ihres Namens. */
+export interface MarkerName { id: number; x: number; y: number; width: number; height: number }
+export interface PlacedMarkerName { id: number; slot: MarkerNameSlot | 'hidden'; rect?: ScreenRect }
+
+/** Der Kasten eines Namens an einem Platz, in Bildschirmpixeln. */
+export function markerNameRect(marker: MarkerName, slot: MarkerNameSlot): ScreenRect {
+ const { x, y, width: w, height: h } = marker;
+ const reach = MARKER_RING_RADIUS + NAME_GAP;
+ const at = (left: number, top: number): ScreenRect => ({ left, top, right: left + w, bottom: top + h });
+ switch (slot) {
+ case 'below': return at(x - w / 2, y + reach);
+ case 'above': return at(x - w / 2, y - reach - h);
+ case 'right': return at(x + reach, y - h / 2);
+ case 'left': return at(x - reach - w, y - h / 2);
+ case 'below-2': return at(x - w / 2, y + reach + h + ROW_GAP);
+ case 'above-2': return at(x - w / 2, y - reach - 2 * h - ROW_GAP);
+ case 'right-up': return at(x + reach, y - h / 2 - h - ROW_GAP);
+ case 'right-down': return at(x + reach, y + h / 2 + ROW_GAP);
+ case 'left-up': return at(x - reach - w, y - h / 2 - h - ROW_GAP);
+ case 'left-down': return at(x - reach - w, y + h / 2 + ROW_GAP);
+ }
+}
+
+const SLOTS: readonly MarkerNameSlot[] = ['below', 'above', 'right', 'left', 'below-2', 'above-2', 'right-up', 'right-down', 'left-up', 'left-down'];
+const hit = (a: ScreenRect, b: ScreenRect) => !(a.right <= b.left || b.right <= a.left || a.bottom <= b.top || b.bottom <= a.top);
+const overlapArea = (a: ScreenRect, b: ScreenRect) => Math.max(0, Math.min(a.right, b.right) - Math.max(a.left, b.left))
+ * Math.max(0, Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top));
+const inside = (rect: ScreenRect, bounds: ScreenRect) => rect.left >= bounds.left && rect.right <= bounds.right && rect.top >= bounds.top && rect.bottom <= bounds.bottom;
+const CENTRED: ReadonlySet<MarkerNameSlot> = new Set(['below', 'above', 'below-2', 'above-2']);
+/* Ein Name ueber oder unter seinem Ring rueckt seitlich in die Zeichenflaeche, solange er den Ring noch ueberspannt. */
+function nudged(marker: MarkerName, slot: MarkerNameSlot, bounds: ScreenRect): ScreenRect {
+ const rect = markerNameRect(marker, slot);
+ if (!CENTRED.has(slot) || marker.width > bounds.right - bounds.left) return rect;
+ const shift = rect.left < bounds.left ? bounds.left - rect.left : rect.right > bounds.right ? bounds.right - rect.right : 0;
+ return Math.abs(shift) <= marker.width / 2 - MARKER_RING_RADIUS / 2 ? { ...rect, left: rect.left + shift, right: rect.right + shift } : rect;
+}
+
+/**
+ * Ein Platz je Name, in der Reihenfolge der Marken: wer zuerst kommt, behaelt
+ * den Platz der Stilvorlage. Kein Name liegt auf einem anderen oder ausserhalb
+ * von `bounds` (der Zeichenflaeche); was keinen Platz findet, ist `hidden`.
+ * Eine Marke, deren Ring ausserhalb liegt, hat dort auch keinen Namen.
+ */
+export function placeMarkerNames(markers: readonly MarkerName[], bounds: ScreenRect): PlacedMarkerName[] {
+ const rings = markers.map((marker) => ({ id: marker.id, rect: { left: marker.x - MARKER_RING_RADIUS, right: marker.x + MARKER_RING_RADIUS,
+ top: marker.y - MARKER_RING_RADIUS, bottom: marker.y + MARKER_RING_RADIUS } }));
+ const placed: ScreenRect[] = [];
+ return markers.map((marker) => {
+ // Among the places clear of other names, the one that covers the least of the other rings; the order of SLOTS breaks ties.
+ let best: { slot: MarkerNameSlot; rect: ScreenRect; covered: number } | undefined;
+ for (const slot of SLOTS) {
+ const rect = nudged(marker, slot, bounds);
+ if (!inside(rect, bounds) || placed.some((other) => hit(rect, other))) continue;
+ const covered = rings.reduce((sum, ring) => sum + (ring.id === marker.id ? 0 : overlapArea(rect, ring.rect)), 0);
+ if (!best || covered < best.covered) best = { slot, rect, covered };
+ if (covered === 0) break;
+ }
+ if (!best) return { id: marker.id, slot: 'hidden' };
+ placed.push(best.rect);
+ return { id: marker.id, slot: best.slot, rect: best.rect };
+ });
+}