Nx Graph library

@nx/graph/legacy

This entry point is mainly for migration purposes. This contains the entire old @nx/graph library.

@nx/graph

Core of Nx Graph that contains base styles, basic types, and logic to render Cytoscape elements.

useRenderGraphEvent

A custom hook that allows consumers to listen for various events on the RenderGraph: the nodes, the edges, the background click

const { graphClient, send } = useProjectGraphClient({
  /*...*/
});

useRenderGraphEvent(graphClient, 'CompositeNodeDblClick', (event) => {
  if (event.isExpanded) {
    send({ type: 'collapseCompositeNode', compositeNodeId: event.id });
  } else {
    send({
      type: 'expandCompositeNode',
      compositeNodeId: event.id,
      mode: 'affected-only',
    });
  }
});

Events

export interface CompositeProjectNodeDblClickEvent {
  type: 'CompositeNodeDblClick';
  id: string;
  isExpanded: boolean;
}

export interface ProjectNodeContextMenuEvent {
  type: 'ProjectNodeContextMenu';
  id: string;
  data: ProjectNodeElementData;
  virtualElement: VirtualElement;
}

export interface CompositeProjectNodeContextMenuEvent {
  type: 'CompositeNodeContextMenu';
  id: string;
  isExpanded: boolean;
  data: CompositeProjectNodeElementData;
  virtualElement: VirtualElement;
}

export interface ProjectEdgeContextMenuEvent {
  type: 'ProjectEdgeContextMenu';
  id: string;
  data: ProjectEdgeElementData;
  virtualElement: VirtualElement;
}

export interface CompositeProjectEdgeContextMenuEvent {
  type: 'CompositeProjectEdgeContextMenu';
  id: string;
  data: CompositeProjectEdgeElementData;
  virtualElement: VirtualElement;
}

export interface EmptyClickEvent {
  type: 'EmptyClick';
}

export interface PostRenderEvent {
  type: 'PostRender';
  cy: Core;
}

export type RenderGraphEvent = CompositeProjectNodeDblClickEvent | ProjectNodeContextMenuEvent | CompositeProjectNodeContextMenuEvent | ProjectEdgeContextMenuEvent | CompositeProjectEdgeContextMenuEvent | EmptyClickEvent | PostRenderEvent;

@nx/graph/projects

This entry point deals with handling ProjectGraph information.

const { containerRef, graphClient, send } = useProjectGraphClient({ renderPlatform: 'nx-cloud' });

• containerRef is used to assign to a div element where the graph will be rendered.
• graphClient can be used with other graph components like useRenderGraphEvent
• send is a function that can send events that the ProjectGraphClient handles

@nx/graph/tasks

This entry point deals with handling TaskGraph information.

const { containerRef, graphClient, send } = useTaskGraphClient({ renderPlatform: 'nx-cloud' });

• containerRef is used to assign to a div element where the graph will be rendered.
• graphClient can be used with other graph components like useRenderGraphEvent
• send is a function that can send events that the TaskGraphClient handles

@nx/graph/ui

This entry point contains various graph UI components

NxGraphBackground

A static background component.

<div className="graph-container relative overflow-hidden">
  <NxGraphBackground />

  <div className="h-full" ref={containerRef} />
</div>

NxGraphControls

A container that holds the graph controls; usually in form of icons

<div className="graph-container relative overflow-hidden">
  <div className="h-full" ref={containerRef} />

  <NxGraphControls>
    <ResetGraphLayoutControl onClick={() => send({ type: 'resetLayout' })} />
    <ResetGraphStateControl onClick={() => send({ type: 'resetGraph', autoExpand: true, mode: 'affected-only' })} />
  </NxGraphControls>
</div>

NxGraphLegends

A collapsible element that renders graph legends

<NxGraphLegends>
  {{
    nodes: (
      <>
        <NodeLegend />
        <CompositeNodeLegend />
        <AffectedNodeLegend />
        {touchedProjects.length > 0 && <TouchedNodeLegend />}
      </>
    ),
    edges: (
      <>
        <EdgeLegend />
        <CompositeEdgeLegend />
      </>
    ),
  }}
</NxGraphLegends>

Pre-build legends

• NodeLegend: legend for a regular node
• CompositeNodeLegend: legend for a composite node
• AffectedNodeLegend: legend for a node whose isAffected is true
• TouchedNodeLegend: legend for a node whose isTouched is true
• EdgeLegend: legend for a regular edge
• CompositeEdgeLegend: legend for a composite edge

All legends can be customized: colors, labels, etc...

@nx/graph/context-menu

Handles context menu of the elements on the graph.

useGraphContextMenu

To enable context menu, useGraphContextMenu hook is required. This hook sets up listeners for various render events and return proper graphMenu object

const { graphMenu, closeMenu } = useGraphContextMenu({
  /* require graphClient or any RenderGraphEventBus */
  renderGraphEventBus: graphClient,
});

NxGraphContextMenu

graphMenu object is used to render NxGraphContextMenu

{
  graphMenu ? (
    <NxGraphContextMenu menu={graphMenu.props} virtualElement={graphMenu.virtualElement} placement="bottom-start">
      {/* {children goes here} */}
    </NxGraphContextMenu>
  ) : null;
}

NxGraphContextMenu only handles the floating menu. To render the content, NxGraphContextMenu accepts a dictionary of children render props

{
  project: ({ id: string, data: ProjectNodeElementData }) => ReactNode;
  compositeProject: ({ id: string, isExpanded: boolean, data: CompositeProjectNodeElementData }) => ReactNode;
}

Each children render prop can render multiple NxGraphContextMenuSection

<NxGraphContextMenu>
  {{
    project: ({ id, data }) => (
      <>
        <NxGraphContextMenuSection>
          <ViewDetailButton />
        </NxGraphContextMenuSection>
        <NxGraphContextMenuSection title="Actions">
          <ExcludeNodeButton />
        </NxGraphContextMenuSection>
      </>
    ),
  }}
</NxGraphContextMenu>

ViewDetailButton and ExcludeNodeButton are implementation details. They can be anything that the consumers want to render in the Project Node's context menu.

@nx/graph/panel

Handles panels in the graph.

NxGraphElementDetailPanel

To render a panel, capture a NodeElementData (via NxGraphContextMenu or useRenderGraphEvent) then use NxGraphElementDetailPanel

<NxGraphElementDetailPanel element={element} onClose={() => setElement(null)}>
  {{
    project: (projectNodeElementData) => <>{/* any content */}</>,
    compositeProject: (compositeProjectNodeElementData) => <>{/* any content */}</>,
  }}
</NxGraphElementDetailPanel>