powsybl-network-viewer

Typescript library to integrate network viewers in a javascript project. This library contains three viewers:

• network-area-diagram-viewer, to integrate the SVG representing a graph of voltage levels within a network, the SVG and the corresponding metadata JSON file being generated by powsybl-diagram
• single-line-diagram-viewer, to integrate the SVG representing single-line diagrams, the SVG and the corresponding metadata JSON file being generated by powsybl-diagram
• network-map-viewer, to display the substations / voltage levels on a map

The library is built with the Vite bundler. Node from v22+ is required to build with Vite.

Note:
A .nvmrc file is present in the repository, please run nvm use to use the expected NodeJS version.

Installation

The library is split into 3 packages to accommodate different use cases:

| Package | Description | |--------------------------------|----------------------------------------------------| | @powsybl/network-viewer | Full package with all viewers including NetworkMap | | @powsybl/network-viewer-core | Core viewers (NAD + SLD) | | @powsybl/network-map-layers | Deck.gl layers for map integration |

For full package

npm install @powsybl/network-viewer

This package requires React peer dependencies:

• react, react-dom, react-intl
• @mui/material, @mui/icons-material, @emotion/styled

For Angular/Vue/Vanilla JS applications (React-free)

If you only need the SVG diagram viewers (NetworkAreaDiagramViewer and SingleLineDiagramViewer) without React:

npm install @powsybl/network-viewer-core

Usage:

import {
    NetworkAreaDiagramViewer,
    SingleLineDiagramViewer,
    LayoutParameters,
    SvgParameters,
} from '@powsybl/network-viewer-core';

// Create NAD viewer
const nadViewer = new NetworkAreaDiagramViewer(
    container,
    svgContent,
    metadata,
    minWidth,
    minHeight,
    maxWidth,
    maxHeight,
    parameters
);

// Create SLD viewer
const sldViewer = new SingleLineDiagramViewer(container, svgContent, metadata, options);

For Deck.gl map layers only

npm install @powsybl/network-map-layers

For developers

For development purpose, to install this library locally from an app, you should run these commands in the library project :

• npm install
• npm run build:all
• npm run pack:all

Then in the app project :

• npm install {PATH_TO_LIBRARY}/powsybl-network-map-layers-{LIBRARY_VERSION}.tgz
• npm install {PATH_TO_LIBRARY}/powsybl-network-viewer-{LIBRARY_VERSION}.tgz

Warning : with Create React App, we realised the library was not updating correctly if you try to install the library multiple times. To fix this, run this command from the app after running "npm install"

• rm -Rf node_modules/.cache

For integrators

(Optional) Test your package from library dependent directory

If you want to deploy a new version of powsybl-network-viewer in the NPM package registry, you need to follow the steps below:

1/ Prepare released version

• Update to the new version in both packages (example 3.2.0):
  npm --workspaces --include-workspace-root --no-git-tag-version version 3.2.0
  Remarks: without --no-git-tag-version the commit doesn't contain both package.json and the complete package-lock.json files then we do it manually next
• Change the version of dependencies in the root package.json to ^3.2.0
• npm i to update package-lock accordingly
• Commit the package.json and package-lock.json files, push to a branch, make a PR, have it reviewed and merged to main with title Bump to 3.2.0.
• Pull and checkout main on your last commit.
• Tag (with -s signed) your last commit :
  git tag -s <tag> (example: git tag -s v3.2.0)
• Push tag :
  git push origin <tag>

2/ Publish version

• Checkout the tag in a fresh repo copy :
  cd $(mktemp -d) && git clone https://github.com/powsybl/powsybl-network-viewer.git then cd powsybl-network-viewer && git checkout <tag>
• Install your packages:
  npm install --workspaces --include-workspace-root
• Build the packages - npm will publish the README.md, the package.json files and the dist directory you just generate :
  npm run build:all
• Login on the command line to the npm registry:
  npm login
• Publish the package:
  npm run publish:all

3/ Prepare next version

• Update to the next version in both packages (example 3.3.0-dev.0):
  npm --workspaces --include-workspace-root --no-git-tag-version version 3.3.0-dev.0
• Change the version of dependencies in the root package.json to ^3.3.0-dev.0
• npm i to update package-lock accordingly
• Commit the package.json and package-lock.json files, push to a branch, make a PR, have it reviewed and merge to main with title Bump to 3.3.0-dev.0.

Notes :

• Check license-checker-config.json for license white list and exclusion. If you need to update this list, please inform organization's owners.
• We need to exclude some packages for now :
  • @mapbox/[email protected] is a special license
  • [email protected] is Creative Commons but not correctly described in the package
  • [email protected] is BSD-3-Clause but not correctly described in the package