GenSpectrum components

This NPM package provides a collection of web components to build interactive dashboards that visualize data of a specific instance of LAPIS.

Documentation

Documentation of the components is available in the deployed Storybook.

We also provide examples of how to use the components in the examples folder.

npm

To install the package, run:

npm i @genspectrum/dashboard-components

Core Concepts

Internally, the components use Preact. We use Lit to create web components.

We primarily provide two kinds of components:

• Visualization components (charts, tables, etc.)
  • Those components fetch data from the LAPIS instance and visualize it.
• Input components that let you specify sequence filters for the LAPIS requests.
  • Input changes will fire events that can be listened to by the visualization components. It is the responsibility of the dashbaord maintainer to listen to those events and to wire the data correctly into the visualization components.

Local Development

Installation

npm ci

Custom Elements Manifest

This package also ships a Custom Elements Manifest, which is a formal specification of the web components. We use the @custom-elements-manifest/analyzer to autogenerate the custom-elements.json file:

npm run generate-manifest

or in watch mode:

npm run generate-manifest:watch

Storybook

We use Storybook to develop our components.

To start Storybook, run (npm run generate-manifest makes sure to generate the custom-elements.json first):

npm run generate-manifest
npm run storybook-preact
npm run storybook

Then, open http://localhost:6006/ and http://localhost:6007/ in your browser. The Storybook on port 6007 uses the Preact build. The Storybook on port 6006 uses the Lit build and includes the Preact Storybook. Note that some Storybook integrations (such as interaction tests) do not work in the included Storybook. We only deploy the Lit part of the Storybook to GitHub pages.

Storybook offers an integration of the custom-elements.json that can generate doc pages for the web components. Refer to the Custom Elements Manifest Docs for how to document the components using JSDoc.

Testing

We use vitest to run our unit tests:

npm run test

We use Storybook and Playwright to test the components in the browser:

npm run test:storybook
npm run test:storybook:preact
npm run test:playwright

This assumes that the Storybooks are running.

We follow this testing concept:

• Domain logic is tested with unit tests. Thus, that code should be kept separate from the components.
• Detailed tests of the components are done with interaction tests in the Preact Storybook.
• The Lit Storybook only contains tests for the most important functionality to ensure that the web component build works.
• We use Playwright for
  • snapshot tests of the visualization components:
    • Screenshots of charts and tables that serve as visual regression.
    • Snapshots of the CSV data that the visualization components offer as download.
  • testing functionality of components that cannot be tested within Storybook due to technical limitations.