Release notes

yFiles for HTML

All changes

Since version 2.5.0.4

New features

View and Styles

• The WebGL2-based selection, highlight, and focus rendering managers can now be used together with SVG-based graph rendering. Any combination of SVG- and WebGL2-based implementations is supported.
• The GraphModelManager.labelLayerPolicy property, which defines whether labels should be rendered at their owner or in a separate layer, has been split into the separate properties nodeLabelLayerPolicy, edgeLabelLayerPolicy, and portLabelLayerPolicy to support different policies for node, edge, and port labels.
• Selection, focus, and highlight visualizations can now be easier customized with a node, edge, label, or port style. These style instances can be set to the corresponding properties of the new GraphSelectionIndicatorManager, GraphFocusIndicatorManager, and GraphHighlightIndicatorManager classes that can be set as corresponding managers on the GraphComponent. This removes the need for using NodeStyleDecorationInstaller, etc.
• To render items in a zoom-invariant fashion, their style can be wrapped in one of the new IndicatorNodeStyleDecorator, IndicatorEdgeStyleDecorator, IndicatorLabelStyleDecorator, or IndicatorPortStyleDecorator classes. The main use case for these decorators is using item styles as selection, focus or highlight indicators.
• The new GraphComponent.SelectionModelChanged event is raised when the model managing the selection is changed itself, not when the selected items change.
• The new TextRenderSupport.invalidateTextMeasurementCache method can be used to reset measure mode detection for a single font or all fonts.

Layout

• The PreferredPlacementDescriptor class now offers two new static factory methods fromModel and fromParameter, to create PreferredPlacementDescriptor instances from ILabelModel and ILabelModelParameter instances, respectively.

• The CircularLayout class now offers the possibility to define star substructures. Its starSubstructureStyle property specifies the style of star substructures and its starSubstructureSize property specifies their minimum size (structures of smaller size are not handled as a star substructure). Furthermore, its starSubstructureTypeSeparation property specifies whether star substructures should be separated by the node type. The new Circular Substructures Demo shows this feature.

  The new CircularLayoutData.edgeDirectedness property specifies how the direction of an edge is considered by the detection of star-substructures.

• The RadialLayout class now supports node types. The types influence the ordering of nodes of the same circle such that nodes of the same type are preferably placed next to each other if this does not induce additional crossings or conflicts with other constraints. Node types can be defined via the RadialLayoutData.nodeTypes property.
• The RadialLayout class now allows defining a custom order of child nodes around a local root node. The order can be individually specified for each node by using the new RadialLayoutData.outEdgeComparers property. It is especially suitable for tree-like input graphs. For specifying a single global order for all nodes, for example, alphabetically, the new RadialLayoutData.nodeComparables property is a more convenient option.
• The OrganicLayout class now provides a feature that dynamically detects whether nodes already lie almost on a common line or circle and, if so, snaps the nodes to this line or circle. This new feature can be enabled with the chainRecognition and circleRecognition properties.
• Data registered with GenericLayoutData is now automatically transferred to a Worker when using LayoutExecutorAsyncWorker.
• The HierarchicLayout class now also considers layering constraints between elements of different grouping hierarchies if the recursive group layering is enabled with the HierarchicLayout.recursiveGroupLayering property. Previously, such constraints were ignored in that case.

Improvements

General

• All yFiles modules can now be loaded in environments with incomplete SVG implementation, such as jsdom, without causing exceptions. It is also possible to create a new GraphComponent in these environments, although many operations on the GraphComponent will still fail.
• License checking is now more careful when testing on non-browser environments and detects them more reliably.

• Obsolete compatibility files for old yFiles versions have been removed.

Graph and collections

• The EdgePathLabelModel and EdgeSegmentLabelModel classes have been improved to provide better placements with edge-cases where the path is too short for the label or degenerates completely.
• The GroupNodeLabelModel class no longer triggers an error when used with or set to a node that does not use GroupNodeStyle. GroupNodeLabelModel is still not intended to be used with nodes that do not use GroupNodeStyle. This restriction has been lifted to support workflows where the node style is set to GroupNodeStyle after the label model is set to GroupNodeLabelModel.
• The List class now implements the IListEnumerable interface. This allows using List instances where an IListEnumerable is expected, e.g., assigning the instance returned by the IEdge.bends.toList method to the SimpleEdge.bends property.
• The types of the IEnumerable.groupBy and IEnumerable.from methods or now properly inferred from their parameters. Similarly, the List.from method can now infer the type argument of the returned list even if no mapFunction argument was passed.
• The Exception class no longer re-declares the cause property, but just inherits it from Error, to make sure that the types don't clash. This has been a problem for TypeScript 4.6 through 4.8.
• Functions that are method parameters now have meaningful parameters names and descriptions for their own parameters. In particular, this applies to the methods of the IEnumerable class.

GraphBuilder

• The NodeCreator, EdgeCreator, and LabelCreator classes can now be used without a GraphBuilder. This enables developers to apply styles and labels from a data object in cases where a GraphBuilder is not suitable for graph creation.
• A NodeSource now allows for recursive definition of child nodes in a grouping hierarchy. The new methods addChildNodesSource and createChildNodesSource allow for defining a source to fetch child node items from a node data item.
• A NodeSource now allows for implicit definition of parent nodes in a grouping hierarchy. The new methods addParentNodesSource and createParentNodesSource allow for defining a source to fetch a parent node item from a node data item.
• The getUpdatedStyle method of the NodeCreator, EdgeCreator, and LabelCreator classes now uses the default style from the graph as fallback if the style provider is not set.
• The LabelCreator.getUpdatedLayoutParameter method now uses the default layout parameter from the graph as fallback if the layout parameter provider is not set.
• The TypeScript types for the graph builders and their sources and creators have been made more precise. Many parameters and providers now support strings, objects, or arrays which can be converted into their actual type.

View and Styles

• All base style classes now have an optional generic type parameter. The type defines the exact type of the visual, making it easier to properly implement custom styles with comprehensive IDE type-checking. In addition, for the SvgVisual and the new HtmlVisual classes, there are now factory methods that help with the type-safe creation of the visual along with a type-safe storage of tag data for the purpose of caching rendering data. See the new custom style tutorial on how to use the new type safety.

  The IRenderContext.setDisposeCallback method has now a type parameter for the type of the Visual it handles.

• Bends in edges that use ArcEdgeStyle, ArrowEdgeStyle, or BridgeEdgeStyle are no longer shown when selecting these edges. Additionally, marquee selection will not select these bends anymore even if they lie in the selection rectangle.
• Changing the height of an arc or bridge edge via its handle is now undoable.
• The MarkupLabelStyle class is now faster when the shown text does not contain HTML, and it can now correctly render <sub> and <sup> elements in Firefox..
• The rendering performance of the ShapeNodeStyle class has been improved.
• Initial text measurement when adding labels with the DefaultLabelStyle or MarkupLabelStyle classes is now faster.
• Text measurement no longer sometimes mistakenly uses a slower method, even though this is not necessary.
• Improved SVG rendering performance when embedded in a framework with extensive CSS resets (e.g., Vuetify, Material UI, ...).
• The rendering order of nodes in the GraphOverviewComponent has been improved to be more in sync with the rendering order in the corresponding GraphComponent.
• The GraphOverviewComponent class now uses its contentGroup instead of the rootGroup to add the visualization of its graph content. This makes it easier to customize the overview, for example, by adding a background visual.

WebGL2 rendering mode

• The WebGL2DefaultLabelStyle class now uses the actual label layout to render the labels at the same positions as DefaultLabelStyle, especially with label models that adjust the label size like InteriorStretchLabelModel and GroupNodeLabelModel.
• WebGL2 labels are now rendered in batches to ensure browser responsiveness when lots of labels must be rendered.
• The GraphOverviewComponent class now supports rendering in WebGL2 using suitable WebGL2 item styles for the nodes and edges. Similarly, the GridVisualCreator class now support rendering in WebGL2, too.
• Automatic conversion of a NodeStyleLabelStyleAdapter instance to a WebGL2 style now yields a closer matching visualization.
• The shader for polyline edges compiles faster when only a subset of visual features like dashed, effect, or smooth bends are enabled.
• The fallback shader for polyline edges now respects bends.
• Several style-related methods of the WebGL2GraphModelManager class have now better types.
• The WebGL2Stroke class now supports type conversion from the Stroke class.
• WebGL2PolylineEdgeStyle now renders polyline edges with smooth bends without artifacts on Android devices that do not have enough mediump precision. These edges will be rendered without smoothing, though.

Interaction

• The ItemDroppedInputMode.DragDropped event is now raised after the drop gesture has actually finished, in line with how similar events are raised elsewhere.
• The MoveInputMode, MoveLabelInputMode, and HandleInputMode sub-modes of the GraphEditorInputMode class no longer have a pre-set SnapContext instance. Instead, they get their SnapContext instance from the InputModeContext. That way, setting the GraphEditorInputMode.snapContext property will affect all sub-modes unless a custom SnapContext is set to them.
• The new protected CreateEdgeInputMode.createDummyBend method can be overridden to customize bends added during edge creation. The new protected CreateEdgeInputMode.dummySourceNodePort property provides the temporary port used during edge creation and simplifies overriding the createDummyEdge method.
• The PortRelocationHandle.createDummyEdge method is now virtual and can be overridden.
• The gesture to start edge creation while dragging inside the source node can now be customized with the new CreateEdgeInputMode.sourceNodeDraggingFinishedRecognizer property.
• To improve the usability of resize handle for small nodes, their rendering order has been adjusted.
• To improve the usability of pen input devices, yFiles is more tolerant of small movements during pressing (similar to touch).
• The HoveredItemChangedEventArgs.item property is now properly annotated as nullable.

Layout

• For oriented rectangles the intersection test no longer allocates unnecessary memory and no longer creates unnecessary objects, which improves its allocation performance.
• The TreeLayout class now places the ports of edges incident to multi-parent nodes and with port constraints (excluding any-side constraints) at the nodes' border. Previously, unlike as for edges incident to other nodes, the edge ports where located at the nodes' center.
• The value type of IncrementalHintItemMappingConvertible is now object instead of any and matches the return type of the factory methods of IIncrementalHintsFactory. This means the union type of HierarchicLayoutData.incrementalHints no longer contains any.

Bugfixes

Graph

• The EdgePathLabelModel.findBestParameter method now creates correct parameters for locations close to bends.
• NinePositionsEdgeLabelModel center placements above and below the edge have been improved when the angle wasn't close to one of the two coordinate axes and the distance was non-zero. Previously, labels could seem to jump around when the path changed and weren't always close to the center of the path.
• GroupNodeLabelModel no longer stretches tab labels and tab background labels into the collapse/expand icon of the corresponding GroupNodeStyle.
• The findBestParameter methods of EdgePathLabelModel, EdgeSegmentLabelModel, and SmartEdgeLabelModel now create correct parameters for label boxes that overlap the edge's source or target node.
• GroupingSupport's methods enlargeGroupNode and enlargeAllGroupNodes no longer create empty undo units if nothing has changed.
• Passing an IEnumerable as data to GraphBuilder, TreeBuilder, or AdjacencyGraphBuilder now behaves correctly in environments without Symbol, such as Internet Explorer.
• Fixed a bug in LabelCreator which caused setting preferredSizeBindings to result either in nothing or an error.

View and Styles

• GroupNodeStyle's collapse and expand icon can now be reliably hit in all cases. In rare cases, changing the value of one the properties that affect the icon's location were not taken into account for hit tests.
• The GroupNodeStyle class now shows the icon in a way that renders correctly in non-browser SVG renderers.
• The DefaultLabelStyle class now adds an ellipsis more reliably at the end when the text does not fit into the specified text wrapping shape.
• Bezier edges no longer turn into polyline paths under rare circumstances.
• The ArrowEdgeStyle class now correctly determines its visibility with thicknesses greater than 13.
• The IArrow type converter no longer produces arrows of incorrect size when strings are given that contain only the arrow color in hex and the arrow type, omitting the scale parameter.
• CSS 4 generic font-family names are no longer quoted erroneously when passed to the Font constructor (or used in font conversions).
• The drop shadows created with the ShadowNodeStyleDecorator class are no longer cut off for small node sizes.
• The drop shadow of the GroupNodeStyle class is now correctly displayed in the top left part if the corner radius is greater than 16.
• Animated viewport changes of a GraphComponent no longer cause strange behavior when values for maximum or minimum zoom are set and are also violated by the viewport change.
• Layout animation performance has been improved for edges with many bends.

Interaction

• Self-loops no longer disappear when resizing nodes while orthogonal editing is enabled.
• MoveViewportInputMode's inertia feature is now less easy to trigger when the mouse or touch pointer has stopped moving for some time before releasing the mouse or touch pointer.
• Starting a CanvasComponent or GraphComponent viewport animation now properly stops a running MoveViewportInputMode inertia animation.
• The direction of the first edge segment during orthogonal edge creation is now correctly determined when the source port candidate lies on the node border.
• Fixed a bug in some input modes which led to undefined behavior if the mode has been uninstalled in a handler for its own events.
• SmartEdgeLabelModel now properly supports the original position snap line.
• Pinch-zooming no longer jitters when dragging one or more touch points beyond the canvas borders.
• The NavigationInputMode.expandGroup, NavigationInputMode.enterGroup methods, and the ICommand.EXPAND_GROUP and ICommand.ENTER_GROUP commands do not create empty undo units anymore if nothing has changed.
• The NavigationInputMode.exitGroup method and the ICommand.EXIT_GROUP command now create undo units if the bounds of the exited group node were adjusted.
• Fixed a bug in HighlightIndicatorManager that could result in missing or surplus highlight visualizations when changing the GraphComponent.highlightIndicatorManager property.
• Fixed pixelated rendering of handles when a HandleInputMode.renderMode other than RenderModes.SVG was used in combination with a GraphComponent.theme.scale larger than 1.0.
• The Workarounds.touchstartPreventDefault property now is only enabled by default on iOS devices. Before, it has been enabled on all touch devices, preventing the contextmenu event from being dispatched on certain non-iOS browsers and devices.
• Fixed snapping overwrite with CTRL modifier in Firefox on macOS caused by bogus mouse events on these clients.

WebGL2 rendering mode

• WebGL2 rendering mode no longer tries to update the label texture position in the texture atlas if no texture is assigned.
• WebGL2 rendering of edges is now updated correctly when they are reconnected to different ports.
• Layout morph animations with WebGL2 rendering started immediately at app startup now correctly morph the graph.
• The displayed label text is now correctly updated in rendering mode when the label text changes.
• Group node styles are now correctly converted to expanded WebGL2 group node styles.
• WebGL2 rendering no longer breaks if a graph with group nodes is replaced with a graph that does not contain group nodes.
• WebGL2 rendering no longer throws an error when the graph instance is replaced while a label is selected.
• The IconLabelStyle class can now be auto-converted to a WebGL2IconLabelStyle class without throwing an error. Note however that in this case, the WebGL2 style will render only the label text, not the icon.

Layout

• For hierarchical layouts, rare combinations of PortCandidates in PortCandidateSets no longer result in exceptions.
• In organic layouts, fixed nodes no longer move in any case when also a group node is marked as fixed.
• The OrthogonalLayout class no longer throws an exception for some input graphs with tree substructures when the treeStyle property is set to a value different from TreeLayoutStyle.NONE.
• The EdgeRouter class does no longer yield different results in rare cases when the same instance is applied twice to the same input graph.
• The EdgeRouter class no longer produces self-crossing routes of edges with labels if its integratedEdgeLabeling property is enabled.
• The EdgeRouter class no longer produces bad layout results for some scenarios with grouped edges and multiple PortCandidates. Previously, the algorithm selected any of them without considering the alternative options.
• The ClearAreaLayout class no longer produces results where the specified area is not cleared for some input graphs when its clearAreaStrategy property is set to ClearAreaStrategy.PRESERVE_SHAPES or ClearAreaStrategy.PRESERVE_SHAPES_UNIFORM.
• The PartialLayout class does no longer yield different results in rare cases when the same instance is applied twice to the same input graph.
• The PartialLayout class now correctly places disconnected components for cases where a layout orientation is specified, and its componentAssignmentStrategy property is not ComponentAssignmentStrategy.SINGLE. Previously, such components were sometimes placed far away from the remaining graph elements.
• The ShortestPaths class now correctly calculates the k-shortest paths of graphs. Previously, in rare cases, the algorithm sometimes produces wrong results, i.e., returns paths that are not the shortest.

Notable demo improvements

In addition to the demos for new yFiles features, the extensive demo modernization, and the new tutorials, all listed above, there have been numerous improvements of demo source code. The most notable ones are listed below. To check out the new demos in the demo overview, filter it to the version "v2.6.0.0".

• We modernized the existing demos for testing frameworks, and added several new ones, namely Jest, Jest Puppeteer, Cypress, Playwright, Selenium Webdriver, Vitest, and WebDriverIO.
• Several new demos show how to use UI framework components as node styles in a React, Vue, and Angular app.
• The new WebGL2 Label Fading Demo shows how to create a level-of-detail behavior by fading graph items in WebGL2.
• The new Neighborhood Circles Demo shows the neighborhood of selected nodes arranged on concentric circles. The concentric arrangement highlights how close the connection between a selected node and a neighbor node is.
• Two new demos show the integration of yFiles in Next.js and SolidJS apps, respectively.
• The React Demo is now based on Vite instead of create-react, and the new React Class Components Demo shows a hooks-only approach in contrast to the class component-based approach of the existing demo.
• The Vue Demo is now based on create-vue and thus uses Vue 3, TypeScript, and Vite.
• As part of the demo modernization, demos now make use of modern ECMAScript features when appropriate, and consequently, we dropped support for Internet Explorer for the demos. Note that the yFiles for HTML library itself is still compatible with Internet Explorer 9-11.
• We removed some obsolete demos from the yFiles package, but the last version of their source code is still available in the release 2.5.0.4 of the yfiles-for-html-demos GitHub repo.
• All demos will now be part of the Layout and Viewer yFiles packages. With a viewer-only library, you still won't be able to run a demo that uses the layout part of the API, and vice versa, but you can now easily browse the source code of such demos in your IDE.
• We have changed the category/directory of some demos to improve discoverability. For example, 'complete' has now the more descriptive name 'showcase', and some of its demos moved to other categories like Layout and Styles.

Incompatible Changes

See the Migration Guide for more details and advice on migrating.

Incompatible API Changes

• The CactusGroupLayout's defaultNodeComparator property has been renamed to defaultNodeComparer.
• The StarSubstructureStyle enum has been renamed to OrganicLayoutStarSubstructureStyle since there is now also a CircularLayoutStarSubstructureStyle with different values.
• The GraphModelManager.labelLayerPolicy property has been marked as deprecated and will be removed in a future release. Use the more specific properties nodeLabelLayerPolicy, edgeLabelLayerPolicy, and portLabelLayerPolicy instead.
• The TreeNodeSource and AdjacencyNodesSource classes no longer inherit from NodeSource. Consequently, the TreeBuilder.setData method now only accepts TreeNodesSource instances instead of NodesSource instances as its nodesSource parameter.
• The HoveredItemChangedEventArgs class is no longer a subclass of the unrelated ItemEventArgs class. Nevertheless, it still has the same members as before.
• The type of the nodeStyle properties of the WebGL2SelectionIndicatorManager, WebGL2HighlightIndicatorManager, and WebGL2FocusIndicatorManager classes changed from WebGL2NodeIndicatorStyle to WebGL2NodeIndicatorStyle | WebGL2BeaconNodeIndicatorStyle.
• The YObject.referenceEquals method has been removed. We don't expect anyone to have used this method, and it can simply be replaced with the === operator.

Incompatible behavior changes

• When IEnumerable.orderBy and IEnumerable.orderByDescending are called without a comparison function, they now sort numbers by their numerical values. Before, they were sorted by their string values.
• The ItemDroppedInputMode.dragDropped event is now raised after the drop gesture has actually finished, in line with how similar events are raised elsewhere.
• Bends in edges that use ArcEdgeStyle, ArrowEdgeStyle, or BridgeEdgeStyle are no longer shown when selecting these edges. Additionally, marquee selection will not select these bends anymore even if they are in the selection rectangle. This is because these styles either consider bends as control points or do not consider them at all.
• The MoveInputMode, MoveLabelInputMode, and HandleInputMode sub-modes of GraphEditorInputMode no longer have a pre-set snapContext. Instead, they take the SnapContext instance from the input mode context. That way, changing the GraphEditorInputMode.snapContext property will also affect these sub-modes.
• EdgePathLabelModel and EdgeSegmentLabelModel have been modified to yield better results when the path is not long enough for the label or even completely invisible due to overlapping nodes. This leads to greater visual stability in such cases, but results in slightly different placements in these edge cases.
• Adding a label with GroupNodeLabelModel to a node that does not use GroupNodeStyle or setting a GroupNodeLabelModel-created parameter for a label whose owner node does not use GroupNodeStyle no longer throws an error claiming "The parameter does not support this kind of label.".
• For GroupNodeStyle and WebGL2GroupNodeStyle, if the tab width is set to 0, the tab width does not reduce the corner radius of the style's outline anymore. However, it still forces the corner radius of the style's inner corners (i.e. the corners of the content area on the side of the style's tab) to 0.
• The TextRenderSupport.addText method now consistently returns a string containing line breaks for wrapped texts.
• The EdgeRouter class now ignores inner node labels by default, see property ignoreInnerNodeLabels. Previously, this property was disabled by default.
• The layout-radial module now depends on the layout-tree module. Since you typically import from yfiles and not an individual module, this doesn't affect your source code. However, build tools that do tree shaking will now include the layout-tree module together with the layout-radial module.