fCoSE Layout for Cytoscape.js

Common errors

• TypeError: Cannot read properties of undefined (reading 'layout')

  cause The `fcose` layout extension has not been properly registered with your Cytoscape.js instance before attempting to use it.
  fix Ensure you call `cytoscape.use(fcose);` after importing the `cytoscape-fcose` module and before initializing any Cytoscape.js instances or calling `cy.layout({ name: 'fcose' })`.

• Error: The layout 'fcose' is not registered.

  cause The `fcose` layout extension module was imported but not correctly registered with Cytoscape.js, or the registration happened after an attempt to use the layout.
  fix Verify that `import fcose from 'cytoscape-fcose';` and `cytoscape.use(fcose);` are executed at an appropriate place in your application setup, typically at the entry point or before any graph initialization.

• Error: `alignmentConstraint` must be given in most compact form. Example: `['n1', 'n2', 'n3']` instead of `['n1', 'n2'], ['n1', 'n3']`.

  cause Your `alignmentConstraint` configuration contains redundant or non-compact array definitions for nodes that should be aligned.
  fix Refactor your `alignmentConstraint` to group all nodes that should be aligned in a single direction (vertical or horizontal) into one sub-array. For example, change `vertical: [['n1', 'n2'], ['n1', 'n3']]` to `vertical: [['n1', 'n2', 'n3']]`.

Warnings

• breaking Version 2.0.0 introduced significant new features including user-specified constraint support (fixed node, alignment, relative placement) and per-element values for options like `nodeRepulsion`, `edgeElasticity`, and `idealEdgeLength`. While existing configurations might still work, the structure of layout options for constraints is new and may require updating if attempting to use these advanced features.
  Fix: Review the fCoSE documentation for the new `fixedNodeConstraint`, `alignmentConstraint`, and `relativePlacementConstraint` options and update your layout configuration accordingly to leverage or properly handle these new features.
• gotcha When defining `alignmentConstraint`, arrays for vertical or horizontal alignment must be provided in the 'most compact form'. For instance, instead of `[['n1', 'n2'], ['n1', 'n3']]` for vertical alignment, use `[['n1', 'n2', 'n3']]`.
  Fix: Consolidate your alignment constraint arrays to include all co-aligned nodes in a single sub-array, e.g., `vertical: [['node1', 'node2', 'node3']]`.
• gotcha The `cytoscape-fcose` extension has a peer dependency on `cytoscape` version `^3.2.0`. Using an incompatible major version of Cytoscape.js (e.g., Cytoscape.js v2.x or v4.x) may lead to runtime errors or unexpected layout behavior.
  Fix: Ensure your project's installed `cytoscape` version is compatible with `^3.2.0` (e.g., `npm install cytoscape@^3.2.0`). Check your `package.json` and `npm list cytoscape`.
• deprecated The `numeric.js` dependency was removed in v1.2.2, contributing to performance improvements. While not a direct breaking change for most users, it signifies internal refactoring.
  Fix: No direct action required for users; this was an internal dependency removal. Ensure you are on a recent version to benefit from performance improvements.

Install

• npm install cytoscape-fcose npm
• yarn add cytoscape-fcose yarn
• pnpm add cytoscape-fcose pnpm

Imports

• fcose
  wrong:

  import { fcose } from 'cytoscape-fcose';

  correct:

  import fcose from 'cytoscape-fcose';
  // then register with cytoscape
  cy.use(fcose);

  The extension is typically imported as a default export and then registered with `cytoscape.use()`.
• fcose (CommonJS)
  wrong:

  const { fcose } = require('cytoscape-fcose');

  correct:

  const fcose = require('cytoscape-fcose');
  // then register with cytoscape
  cy.use(fcose);

  For CommonJS environments, `require()` is used to get the default export for registration.
• LayoutOptions type (TypeScript)

  import cytoscape, { LayoutOptions } from 'cytoscape';
  // then use:
  const options: LayoutOptions = { name: 'fcose', ... };

  While `cytoscape-fcose` doesn't export its own specific types directly for layout options, you typically use `LayoutOptions` from `cytoscape` itself for type safety when configuring the layout.

Quickstart

This code initializes a Cytoscape.js instance, registers the `fcose` layout extension, defines a sample graph with compound nodes, and applies the fCoSE layout with animation and custom constraints for fixed node positions and alignment.

import cytoscape from 'cytoscape';
import fcose from 'cytoscape-fcose';

cytoscape.use(fcose);

const cy = cytoscape({
  container: document.getElementById('cy'),
  elements: [
    { data: { id: 'a', parent: 'c' } },
    { data: { id: 'b', parent: 'c' } },
    { data: { id: 'c' } },
    { data: { id: 'd' } },
    { data: { id: 'e' } },
    { data: { id: 'ab', source: 'a', target: 'b' } },
    { data: { id: 'ad', source: 'a', target: 'd' } },
    { data: { id: 'de', source: 'd', target: 'e' } }
  ],
  style: [
    { selector: 'node', style: { 'background-color': '#666', label: 'data(id)' } },
    { selector: '$node > node', style: { 'background-color': '#ccc', 'padding': '10px' } },
    { selector: 'edge', style: { 'width': 3, 'line-color': '#ccc', 'target-arrow-color': '#ccc', 'target-arrow-shape': 'triangle', 'curve-style': 'bezier' } }
  ]
});

const layoutOptions = {
  name: 'fcose',
  animate: true,
  animationDuration: 500,
  // Constraints example: fix node 'd' at a position
  fixedNodeConstraint: [{
    nodeId: 'd',
    position: { x: 300, y: 100 }
  }],
  // Alignment constraint example: align 'a' and 'b' vertically
  alignmentConstraint: {
    vertical: [['a', 'b']],
    horizontal: []
  },
  nodeRepulsion: 4500,
  idealEdgeLength: 50,
  edgeElasticity: 0.45,
  nestingFactor: 0.1,
  numIter: 2500,
  initialEnergyOnIncremental: 0.3 // For incremental layout
};

cy.layout(layoutOptions).run();