Add info control with legend popover to Service map (elastic#270184)

Closes elastic#268609

## Summary

- Add legend to service map
- Fix edges lines during search/highlight


### Before and After

#### Before


https://github.com/user-attachments/assets/131892ee-1e01-4143-8fda-c4c1ec5c1c54

#### After


https://github.com/user-attachments/assets/30242922-5cfc-461d-b97a-9882e8543e7b

<img width="333" height="496" alt="NewLegend"
src="https://github.com/user-attachments/assets/09b19a90-b46f-40d0-8dc9-618f6e16f02b"
/>


### Follow-up required

elastic#270399

Author: sbelastic

src/platform/packages/shared/kbn-doc-links/src/get_doc_links.ts

@@ -54,6 +54,7 @@ export const getDocLinks = ({ kibanaBranch, buildFlavor }: GetDocLinkOptions): D
     apm: {
       kibanaSettings: `${ELASTIC_DOCS}solutions/observability/apm/applications-ui-settings`,
       supportedServiceMaps: `${ELASTIC_DOCS}solutions/observability/apm/service-map`,
+      supportedServiceMapsLegend: `${ELASTIC_DOCS}solutions/observability/apm/service-map#service-maps-legend`,
       customLinks: `${ELASTIC_DOCS}solutions/observability/apm/create-custom-links`,
       droppedTransactionSpans: `${ELASTIC_DOCS}solutions/observability/apm/spans#apm-data-model-dropped-spans`,
       upgrading: `${ELASTIC_DOCS}solutions/observability/apm/upgrade`,

src/platform/packages/shared/kbn-doc-links/src/types.ts

@@ -38,6 +38,7 @@ export interface DocLinks {
   readonly apm: {
     readonly kibanaSettings: string;
     readonly supportedServiceMaps: string;
+    readonly supportedServiceMapsLegend: string;
     readonly customLinks: string;
     readonly droppedTransactionSpans: string;
     readonly upgrading: string;

x-pack/solutions/observability/plugins/apm/public/components/app/service_map/constants.ts

@@ -79,6 +79,7 @@ export const MOCK_EUI_THEME = {
     mediumShade: '#98A2B3',
     primaryText: '#0077CC',
     textPrimary: '#1a1c21',
+    textSubdued: '#69707D',
     emptyShade: '#fff',
     backgroundBasePlain: '#fff',
     backgroundBaseHighlighted: '#F6F9FC',

x-pack/solutions/observability/plugins/apm/public/components/app/service_map/get_highlight_offset.ts

@@ -0,0 +1,62 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import { useCallback } from 'react';
+import { Position, useReactFlow } from '@xyflow/react';
+import { useEuiTheme } from '@elastic/eui';
+import { SERVICE_NODE_CIRCLE_SIZE } from '../../../../common/service_map/constants';
+
+/**
+ * Hook that returns a function to compute adjusted edge endpoints.
+ * Encapsulates access to React Flow internal nodes and EUI theme values
+ * so the edge component doesn't need to manage those concerns.
+ */
+export function useAdjustedEndpoint() {
+  const { getInternalNode } = useReactFlow();
+  const { euiTheme } = useEuiTheme();
+  const wrapperInset = parseInt(euiTheme.size.m, 10);
+  const smallestSize = parseInt(euiTheme.size.xxs, 10);
+  const smallerSize = parseInt(euiTheme.size.xs, 10);
+
+  return useCallback(
+    (
+      nodeId: string,
+      x: number,
+      y: number,
+      refX: number,
+      refY: number,
+      position: Position
+    ): { x: number; y: number } => {
+      const node = getInternalNode(nodeId);
+
+      let offset = wrapperInset;
+
+      if (node?.measured) {
+        const { width, height } = node.measured;
+
+        if (position === Position.Left || position === Position.Right) {
+          offset = Math.max(
+            ((width ?? 0) - SERVICE_NODE_CIRCLE_SIZE) / 2 + smallerSize,
+            wrapperInset
+          );
+        } else if (position === Position.Bottom) {
+          const nodeHeight = height ?? 0;
+          offset = Math.max(
+            nodeHeight - SERVICE_NODE_CIRCLE_SIZE / 2 - (wrapperInset - smallestSize) * 3,
+            wrapperInset
+          );
+        }
+      }
+
+      if (position === Position.Left || position === Position.Right) {
+        return { x: x + (refX > x ? offset : -offset), y };
+      }
+      return { x, y: y + (refY > y ? offset : -offset) };
+    },
+    [getInternalNode, wrapperInset, smallestSize, smallerSize]
+  );
+}

x-pack/solutions/observability/plugins/apm/public/components/app/service_map/graph.tsx

@@ -61,6 +61,7 @@ import {
   ServiceMapOptionsPanelToggle,
   type ServiceMapOrientation,
 } from './service_map_options_panel';
+import { ServiceMapLegend } from './service_map_legend';
 import type { Environment } from '../../../../common/environment_rt';
 import {
   isServiceNode,
@@ -210,12 +211,24 @@ function GraphInner({
 
   useEffect(() => {
     setNodes(nodesWithContextHighlight);
-    setEdges(
-      applyEdgeHighlighting(edgesAfterFilters, {
-        selectedNodeId: selectedEdgeForPopoverRef.current ? null : selectedNodeIdRef.current,
-        selectedEdgeId: selectedEdgeForPopoverRef.current,
-      })
-    );
+
+    const highlightedEdges = applyEdgeHighlighting(edgesAfterFilters, {
+      selectedNodeId: selectedEdgeForPopoverRef.current ? null : selectedNodeIdRef.current,
+      selectedEdgeId: selectedEdgeForPopoverRef.current,
+    });
+
+    const edgesWithContextHighlight = highlightedServiceName
+      ? highlightedEdges.map((edge) => ({
+          ...edge,
+          data: {
+            ...edge.data,
+            sourceContextHighlight: edge.source === highlightedServiceName,
+            targetContextHighlight: edge.target === highlightedServiceName,
+          },
+        }))
+      : highlightedEdges;
+
+    setEdges(edgesWithContextHighlight as ServiceMapEdgeType[]);
 
     if (nodesAfterFilters.length > 0) {
       const timer = setTimeout(() => fitView(getFitViewOptions()), FIT_VIEW_DEFER_MS);
@@ -230,6 +243,7 @@ function GraphInner({
     applyEdgeHighlighting,
     getFitViewOptions,
     nodesAfterFilters.length,
+    highlightedServiceName,
   ]);
 
   const handleNodeClick: NodeMouseHandler<ServiceMapNode> = useCallback(
@@ -637,6 +651,15 @@ function GraphInner({
                     )}
                   </EuiFlexGroup>
                 </EuiPanel>
+                <EuiPanel
+                  hasBorder
+                  hasShadow={false}
+                  paddingSize="none"
+                  borderRadius="m"
+                  grow={false}
+                >
+                  <ServiceMapLegend controlIconCss={mapToolbarControlIconCss} />
+                </EuiPanel>
               </div>
               {!isEmbedded && panelExpanded && (
                 <ServiceMapOptionsPanel

x-pack/solutions/observability/plugins/apm/public/components/app/service_map/graph_controls.test.tsx

@@ -83,6 +83,21 @@ jest.mock('./service_map_minimap', () => ({
   ServiceMapMinimap: () => <div data-testid="react-flow-minimap" />,
 }));
 
+jest.mock('../../../context/apm_plugin/use_apm_plugin_context', () => ({
+  useApmPluginContext: () => ({
+    core: {
+      docLinks: {
+        links: {
+          apm: {
+            supportedServiceMaps: 'https://example.com/docs',
+            supportedServiceMapsLegend: 'https://example.com/docs#service-maps-legend',
+          },
+        },
+      },
+    },
+  }),
+}));
+
 const createMockNode = (id: string, label: string): ServiceMapNode => ({
   id,
   position: { x: 100, y: 100 },

x-pack/solutions/observability/plugins/apm/public/components/app/service_map/graph_minimap.test.tsx

@@ -21,6 +21,23 @@ jest.mock('@elastic/eui', () => {
   };
 });
 
+jest.mock('../../../context/apm_plugin/use_apm_plugin_context', () => ({
+  useApmPluginContext: () => ({
+    core: {
+      docLinks: {
+        links: {
+          apm: {
+            supportedServiceMaps:
+              'https://www.elastic.co/guide/en/kibana/current/service-maps.html',
+            supportedServiceMapsLegend:
+              'https://www.elastic.co/guide/en/kibana/current/service-maps.html#service-maps-legend',
+          },
+        },
+      },
+    },
+  }),
+}));
+
 jest.mock('./use_keyboard_navigation', () => ({
   useKeyboardNavigation: jest.fn(() => ({
     screenReaderAnnouncement: '',

x-pack/solutions/observability/plugins/apm/public/components/app/service_map/graph_screen_reader.test.tsx

@@ -19,6 +19,22 @@ jest.mock('@elastic/eui', () => {
     useEuiTheme: () => ({ euiTheme: MOCK_EUI_THEME_FOR_USE_THEME }),
   };
 });
+
+jest.mock('../../../context/apm_plugin/use_apm_plugin_context', () => ({
+  useApmPluginContext: () => ({
+    core: {
+      docLinks: {
+        links: {
+          apm: {
+            supportedServiceMaps: 'https://example.com/docs',
+            supportedServiceMapsLegend: 'https://example.com/docs#service-maps-legend',
+          },
+        },
+      },
+    },
+  }),
+}));
+
 let mockScreenReaderAnnouncementValue = '';
 const mockSetScreenReaderAnnouncement = jest.fn();
 

x-pack/solutions/observability/plugins/apm/public/components/app/service_map/service_map_edge.tsx

@@ -6,11 +6,15 @@
  */
 
 import React, { memo } from 'react';
-import { BaseEdge, getBezierPath, type EdgeProps } from '@xyflow/react';
+import { BaseEdge, getBezierPath, Position, type EdgeProps } from '@xyflow/react';
+import { useServiceMapSearchContext } from '../../shared/service_map/service_map_search_context';
+import { useAdjustedEndpoint } from './get_highlight_offset';
 
 export const ServiceMapEdge = memo(
   ({
     id,
+    source,
+    target,
     sourceX,
     sourceY,
     targetX,
@@ -20,13 +24,28 @@ export const ServiceMapEdge = memo(
     style,
     markerEnd,
     markerStart,
+    data,
   }: EdgeProps) => {
+    const { activeMatchNodeId } = useServiceMapSearchContext();
+    const adjustEndpoint = useAdjustedEndpoint();
+
+    const sourceHighlighted = Boolean(data?.sourceContextHighlight) || activeMatchNodeId === source;
+    const targetHighlighted = Boolean(data?.targetContextHighlight) || activeMatchNodeId === target;
+
+    const { x: sX, y: sY } = sourceHighlighted
+      ? adjustEndpoint(source, sourceX, sourceY, targetX, targetY, sourcePosition ?? Position.Right)
+      : { x: sourceX, y: sourceY };
+
+    const { x: tX, y: tY } = targetHighlighted
+      ? adjustEndpoint(target, targetX, targetY, sourceX, sourceY, targetPosition ?? Position.Left)
+      : { x: targetX, y: targetY };
+
     const [edgePath] = getBezierPath({
-      sourceX,
-      sourceY,
+      sourceX: sX,
+      sourceY: sY,
       sourcePosition,
-      targetX,
-      targetY,
+      targetX: tX,
+      targetY: tY,
       targetPosition,
     });
 

x-pack/solutions/observability/plugins/apm/public/components/app/service_map/service_map_legend.test.tsx

@@ -0,0 +1,78 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import React from 'react';
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { css } from '@emotion/react';
+import { ServiceMapLegend } from './service_map_legend';
+import { MOCK_EUI_THEME_FOR_USE_THEME } from './constants';
+
+const MOCK_DOCS_LINK = 'https://www.elastic.co/docs/apm/service-maps#service-maps-legend';
+
+jest.mock('@elastic/eui', () => {
+  const original = jest.requireActual('@elastic/eui');
+  return {
+    ...original,
+    useEuiTheme: () => ({ euiTheme: MOCK_EUI_THEME_FOR_USE_THEME }),
+  };
+});
+
+jest.mock('../../../context/apm_plugin/use_apm_plugin_context', () => ({
+  useApmPluginContext: () => ({
+    core: {
+      docLinks: {
+        links: {
+          apm: {
+            supportedServiceMaps: MOCK_DOCS_LINK,
+            supportedServiceMapsLegend: MOCK_DOCS_LINK,
+          },
+        },
+      },
+    },
+  }),
+}));
+
+const controlIconCss = css`
+  min-inline-size: 32px;
+  min-block-size: 32px;
+`;
+
+describe('ServiceMapLegend', () => {
+  it('renders the legend button without errors', () => {
+    render(<ServiceMapLegend controlIconCss={controlIconCss} />);
+
+    const button = screen.getByTestId('serviceMapLegendButton');
+    expect(button).toBeInTheDocument();
+    expect(button).toHaveAttribute('aria-label', 'Legend');
+  });
+
+  it('opens the popover when the button is clicked', async () => {
+    render(<ServiceMapLegend controlIconCss={controlIconCss} />);
+
+    expect(screen.queryByText('Node shapes')).not.toBeInTheDocument();
+
+    await act(async () => {
+      fireEvent.click(screen.getByTestId('serviceMapLegendButton'));
+    });
+
+    expect(screen.getByText('Node shapes')).toBeInTheDocument();
+    expect(screen.getByText('Connections')).toBeInTheDocument();
+    expect(screen.getByText('Anomaly score')).toBeInTheDocument();
+  });
+
+  it('renders the docs link pointing to the service maps documentation', async () => {
+    render(<ServiceMapLegend controlIconCss={controlIconCss} />);
+
+    await act(async () => {
+      fireEvent.click(screen.getByTestId('serviceMapLegendButton'));
+    });
+
+    const docsLink = screen.getByTestId('serviceMapLegendDocsLink');
+    expect(docsLink).toBeInTheDocument();
+    expect(docsLink).toHaveAttribute('href', MOCK_DOCS_LINK);
+  });
+});