docs(components): polish README

resolves #129

components/README.md

@@ -1,23 +1,108 @@
 # GenSpectrum components
 
-## Storybook
+This NPM package provides a collection of web components to build interactive dashboards that visualize
+data of a specific instance of [LAPIS](https://github.com/GenSpectrum/LAPIS).
+
+### Documentation
+
+Documentation of the components is available in the deployed [Storybook](https://genspectrum.github.io/dashboards/).
+
+We also provide examples of how to use the components in the [examples](../examples) folder.
+
+### npm
+
+To install the package, run:
+
+```bash
+npm i @genspectrum/dashboard-components
+```
+
+### Core Concepts
+
+Internally, the components use [Preact](https://preactjs.com/).
+We use [Lit](https://lit.dev/) 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
+
+```bash
+npm ci
+```
+
+### Custom Elements Manifest
+
+This package also ships a [Custom Elements Manifest](https://custom-elements-manifest.open-wc.org/),
+which is a formal specification of the web components.
+We use the `@custom-elements-manifest/analyzer` to autogenerate the `custom-elements.json` file:
+
+```bash
+npm run generate-manifest
+```
+
+or in watch mode:
+
+```bash
+npm run generate-manifest:watch
+```
+
+### Storybook
 
 We use Storybook to develop our components.
 
 To start Storybook, run:
 
 ```bash
+npm run storybook-preact
 npm run storybook
 ```
 
-Then, open http://localhost:6006/ in your browser.
+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.
 
-## Testing
+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](https://custom-elements-manifest.open-wc.org/analyzer/getting-started/#documenting-your-components)
+for how to document the components using JSDoc.
 
-We use vitest to run our unit tests.
+### Testing
 
-To run tests, run:
+We use vitest to run our unit tests:
 
 ```bash
 npm run test
 ```
+
+We use Storybook and Playwright to test the components in the browser:
+
+```bash
+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.

components/package.json

@@ -32,6 +32,7 @@
         "lint:eslint": "eslint 'src/**/*.{ts,tsx}'",
         "lint:lit-analyzer": "lit-analyzer",
         "generate-manifest": "npx custom-elements-manifest analyze --litelement --globs src/web-components/**",
+        "generate-manifest:watch": "npm run generate-manifest -- --watch",
         "format": "prettier \"**/*.{cjs,html,js,json,md,ts,tsx}\" --ignore-path ./.eslintignore --write",
         "check-format": "prettier --check \"**/*.{ts,tsx,json,md,mdx,mjs,cjs}\"",
         "check-types": "tsc --noEmit",