Flowchart

• A glimpse of all main features of the Flowchart.
• The detailed description of these features are provided in respective sections.

Building Blocks

The following are the basic building blocks required to render a flowchart:

1. elements: An array of elements where each element must have following fields:

   • id: ID of the element
   • type: type of element, a config corresponding to this type must be present in elementTypeConfigs
   • settings: This object must contain position (row, column in terms of diagram container) and style
   • left: The absolute left position in pixels
   • top: The absolute top position in pixels
   • width: The width of element in pixels
   • height: The height of element

   Note: If autolayout is enabled, then placement of nodes is calculated automatically, hence can provide any values of left, top and settings.position

   Eg:

   {
       id: 'node-1',
       type: 'ACTION',
       settings: { position: { row: 1, column: 1 }, style: {} },
       left: 20,
       top: 20,
       width: 128
       height: 48,
   }

2. connections: An array of connections where each connection must have following fields:

   • id: ID of connection
   • type: It must be SEQUENCE_FLOW
   • sourceActivityId: ID of source element
   • targetActivityId: ID of target element

   Eg:

   {
       id: 'node-1__node-2',
       type: 'SEQUENCE_FLOW',
       sourceActivityId: 'node-1',
       targetActivityId: 'node-2'
   }

3. elementTypeConfigs: An object which defines config for each unique element type and also for connection (SEQUENCE_FLOW). Each config of element must have following fields:

   • renderer: The component which is used to render the element. It accepts element, index and onAction
   • EntityClass: Should either be BaseElement or Connection
   • adapter: It takes partial element and any values and returns the complete element, mainly used to create new element of this type.
   • width: The common width for all elements of this type
   • height: The common height for all elements of this type

   Eg:

   {
       ACTION:{
           renderer: ({element, index, onAction}) => <div>{element.id}</div>,
           EntityClass: BaseElement,
           adapter: (element, params) => ({ ...element, ...params, type: 'ACTION' }),
           width: 128,
           height: 48,
       }
       SEQUENCE_FLOW:{
           EntityClass: Connection
       }
   }

4. onAction: This should handle actions triggered from inside of flowchart and update the flowchart state accordingly.

   Eg:

   const onAction = action => {
              switch (action.type) {
               case UPDATE_FLOWCHART: {
                      setCanvasState(prevState => ({
                        ...prevState,
                        ...action.payload,
                      }));
                      break;
                    }
                    default:
                  }
               }

5. gridCellDimensions: It defines {width, height, gap} of each grid in flowchart, the position of elements are calculated as a multiple of these.

   Eg:

   {
       width: 32,
       height: 32,
       gap: 2
   }

6. offsets: It defines { topOffset, rowGapOffset } which are used to calculate the position of elements in autolayout mode, by adjusting gap between rows, by the factor of rowGapOffset and top offset of first row by the factor of topOffset.

   Eg:

   {
       topOffset: 1.0,
       rowGapOffset: 1.25,
   }

7. diagramDimensions: It should contain a single field width which is the width of the entire flowchart and is used to calculate the position of elements in autolayout mode.

   Eg:

   {
       width: 800
   }

8. FlowchartStateContext: Since flowchart works in a controlled manner, the state of flowchart is maintained by consumer. We have to wrap the Flowchart component in FlowchartStateContext.Provider passing it the flowchart state which must contain:

   • elements
   • connections
   • elementTypeConfigs

Note: The list above outlines the basic requirements for rendering a flowchart, but there are additional fields, props and state values that enable specific features, which are explained in the examples below.

• Autolayout automatically arrange nodes, thus eliminating the need for manual layouting and is intended to be enabled by default for all new flowcharts.
• Most of the features of flowchart are only available in autolayout mode.
• To enable zoom, pass enableZoom as true.
• By default zoom is enabled if autolayout is enabled

• Pass enableMinimap as true to Flowchart to enable Minimap.
• This feature provides an overview of the flow, rendering small version of each node and showing the current viewport's position relative to the entire flow.
• The Minimap is interactive, clicking at any place in the smaller view will make the flowchart jump to that position.

• For easier navigation of large flowcharts, we can collapse the subtree of any branching node (node having multiple outgoing connections).
• The user can select 3 options from control panel:
  • Initial view: How the nodes are arranged when flowchart first loads
  • Preview for initial view
  • What happens when clicked on expand.
• To enable this, set collapsibleViews in FlowchartState as in the given example.

• We can copy or move a single element or a subtree within a flowchart.
• A copied or moved subtree can only be pasted onto placeholders.
• A single element can be pasted onto placeholders or between connections.
• We can copy a subtree or a single element across different flowcharts of the same flavour within the same session.
• To copy between different flowcharts, the flavour must be included in the canvas state.
• We can also skip a node, which sets its disabled property to true.

• The disconnect button appears when hovering over the connection action (plus icon).
• Set enableAutolayoutOnlyActions to true in the canvas state.
• Available only in EDIT mode.
• The disabledSequence field is set to true when a connection is disconnected.

• The browser’s built-in search doesn’t work due to the flowchart being virtualized, so a custom search is required within the flowchart.
• Use CanvasHeader in renderHeader() and pass it to the Flowchart to enable the search bar.
• Additionally, pass the searchKeys object to define how elements should match the search query.

• highlightIntents is stored in the canvas state, containing three sets: error, success, and warning.
• Each set holds the IDs of elements or connections to be highlighted according to its type (error, success, or warning).
• Highlighting is enabled only in VIEW mode to avoid interference with other actions (e.g., copy, move).
• In VIEW mode, set pathTracingEnabled to true to disable any elements not included in the highlightIntents sets.

• Add a getDimensions function to the element type config to calculate the element's height and width.
• The autolayout algorithm will automatically align nodes at the same level, even when they have different dimensions.

• Add strokeWidth number props in connection.settings to set the width of the connection line. This will also override both paintStyle and hoverWidth,
• Additionally, you can also give className in connection.settings to apply custom styles to the connection line.
• Recommended to use strokeWidth in conjunction with appropriate offsets to avoid clustering of connections.

Purpose - Group Collapse allows us to collapse non-essential nodes in a flow, making it easier to focus on the important parts.

Key Concept

• Nodes that should always remain visible are given a special status by setting isGroupHead = true.
• By default, only groupHead nodes and branching nodes (nodes with multiple children) are visible.

Behavior

• When a groupHead is collapsed, it groups all other nodes in its linear subtree until another groupHead or branching node is encountered.
• Grouping is limited to linear subtrees. If a branching node is found, grouping stops, and all direct children of the branching node are treated as groupHeads to maintain visibility while hiding non-essential nodes.

Example

• In the provided example, Nodes 1, 4, and 13 are explicitly marked as groupHeads.
• Nodes 5, 8, 11, and 12 inherit groupHead status because they are direct children of branching nodes.

Flowchart props