@genspectrum/dashboard-components 0.2.0 → 0.3.1

package/src/web-components/input/introduction.mdx

@@ -0,0 +1,11 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title='Input/Introduction' />
+
+# Introduction
+
+The components in this section let the user specify values for LAPIS filters.
+The filters can then be used as input to the visualization components.
+
+Every component fires `CustomEvent`s when the user interacts with it, which can be used to update the LAPIS filters.
+The `detail` of the event is designed such that it can be directly passed to the LAPIS API.

package/src/web-components/introduction.mdx

@@ -0,0 +1,15 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title='Introduction' />
+
+# Introduction
+
+This 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).
+
+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.

package/src/web-components/visualization/gs-aggregate.stories.ts

@@ -9,7 +9,17 @@ import type { AggregateProps } from '../../preact/aggregatedData/aggregate';
 import './gs-aggregate';
 import '../app';
 
-const meta: Meta<AggregateProps> = {
+const codeExample = `
+<gs-aggregate 
+    fields='["division", "host"]'
+    filter='{"country": "USA"}'
+    views='["table"]'
+    headline="Aggregate"
+    width='100%'
+    height='700px'
+></gs-aggregate>`;
+
+const meta: Meta<Required<AggregateProps>> = {
     title: 'Visualization/Aggregate',
     component: 'gs-aggregate',
     argTypes: {
@@ -18,7 +28,8 @@ const meta: Meta<AggregateProps> = {
             options: ['table'],
             control: { type: 'check' },
         },
-        size: [{ control: 'object' }],
+        width: { control: 'text' },
+        height: { control: 'text' },
         headline: { control: 'text' },
     },
     parameters: withComponentDocs({
@@ -43,7 +54,7 @@ const meta: Meta<AggregateProps> = {
         componentDocs: {
             opensShadowDom: true,
             expectsChildren: false,
-            codeExample: `<gs-aggregate fields='["division", "host"]' filter='{"country": "USA"}' views='["table"]'></gs-aggregate>`,
+            codeExample,
         },
     }),
     tags: ['autodocs'],
@@ -51,14 +62,15 @@ const meta: Meta<AggregateProps> = {
 
 export default meta;
 
-export const Table: StoryObj<AggregateProps> = {
+export const Table: StoryObj<Required<AggregateProps>> = {
     render: (args) => html`
         <gs-app lapis="${LAPIS_URL}">
             <gs-aggregate
                 .fields=${args.fields}
                 .filter=${args.filter}
                 .views=${args.views}
-                .size=${args.size}
+                .width=${args.width}
+                .height=${args.height}
                 .headline=${args.headline}
             ></gs-aggregate>
         </gs-app>
@@ -69,7 +81,8 @@ export const Table: StoryObj<AggregateProps> = {
         filter: {
             country: 'USA',
         },
-        size: { width: '100%', height: '700px' },
+        width: '100%',
+        height: '700px',
         headline: 'Aggregate',
     },
 };

package/src/web-components/visualization/gs-aggregate.tsx

@@ -7,50 +7,65 @@ import { PreactLitAdapterWithGridJsStyles } from '../PreactLitAdapterWithGridJsS
 /**
  * ## Context
  *
- * This component displays aggregated data, which can provide an overview of the underlying data.
+ * This component displays aggregated data in a table, which can provide an overview of the underlying data.
  *
- * It expects a list of fields to aggregate by and a filter to apply to the data.
+ * It expects a list of `fields` to aggregate by and a `filter` to apply to the data.
+ *
+ * ## Views
+ *
+ * ### Table View
+ *
+ * In the table view, the data is presented in a table format where each field is a column,
+ * along with the aggregated value and its proportion.
+ * The proportion represents the ratio of the aggregated value to the total count of the data
+ * (considering the applied filter).
  */
 @customElement('gs-aggregate')
 export class AggregateComponent extends PreactLitAdapterWithGridJsStyles {
     /**
      * The fields to aggregate by.
+     * Every field will be a table column.
+     * Every field must exist in the backing LAPIS instance.
+     *
+     * If left empty, the component will only show the absolute count of the provided `filter` and proportion `100%`.
      */
     @property({ type: Array })
     fields: string[] = [];
 
     /**
-     * The views are used to display the aggregated data.
-     * In the table view, the data is presented in a table format where each field is a column,
-     * along with the aggregated value and its proportion.
-     * The proportion represents the ratio of the aggregated value to the total count of the data
-     * (considering the applied filter).
+     * A list of tabs with views that this component should provide.
      */
     @property({ type: Array })
     views: View[] = ['table'];
 
     /**
      * The filter to apply to the data.
+     * It must be a valid LAPIS filter object.
      */
     @property({ type: Object })
     filter: LapisFilter = {};
 
     /**
-     * The size of the component.
+     * The width of the component.
      *
-     * If not set, the component will take the full width of its container with height 700px.
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
+     */
+    @property({ type: String })
+    width: string = '100%';
+
+    /**
+     * The height of the component.
      *
-     * The width and height should be a string with a unit in css style, e.g. '100%', '500px' or '50vh'.
-     * If the unit is %, the size will be relative to the container of the component.
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
      */
-    @property({ type: Object })
-    size: { width?: string; height?: string } | undefined = undefined;
+    @property({ type: String })
+    height: string = '700px';
 
     /**
      * The headline of the component. Set to an empty string to hide the headline.
      */
     @property({ type: String })
-    headline: string | undefined = 'Aggregate';
+    headline: string = 'Aggregate';
 
     override render() {
         return (
@@ -58,7 +73,8 @@ export class AggregateComponent extends PreactLitAdapterWithGridJsStyles {
                 fields={this.fields}
                 views={this.views}
                 filter={this.filter}
-                size={this.size}
+                width={this.width}
+                height={this.height}
                 headline={this.headline}
             />
         );

package/src/web-components/visualization/gs-mutation-comparison.stories.ts

@@ -16,9 +16,12 @@ const codeExample = String.raw`
     variants='[{ "displayName": "variant1", "lapisFilter": { "country": "Switzerland" }}, { "displayName": "variant2", "lapisFilter": { "country": "Germany" }}]'
     sequenceType="nucleotide"
     views='["table", "venn"]'
+    headline="Mutation comparison"
+    width='100%'
+    height='700px'
 ></gs-mutation-comparison>`;
 
-const meta: Meta<MutationComparisonProps> = {
+const meta: Meta<Required<MutationComparisonProps>> = {
     title: 'Visualization/Mutation comparison',
     component: 'gs-mutation-comparison',
     argTypes: {
@@ -31,7 +34,8 @@ const meta: Meta<MutationComparisonProps> = {
             options: ['table', 'venn'],
             control: { type: 'check' },
         },
-        size: { control: 'object' },
+        width: { control: 'text' },
+        height: { control: 'text' },
         headline: { control: 'text' },
     },
     parameters: withComponentDocs({
@@ -46,14 +50,15 @@ const meta: Meta<MutationComparisonProps> = {
 
 export default meta;
 
-const Template: StoryObj<MutationComparisonProps> = {
+const Template: StoryObj<Required<MutationComparisonProps>> = {
     render: (args) => html`
         <gs-app lapis="${LAPIS_URL}">
             <gs-mutation-comparison
                 .variants=${args.variants}
                 .sequenceType=${args.sequenceType}
                 .views=${args.views}
-                .size=${args.size}
+                .width=${args.width}
+                .height=${args.height}
                 .headline=${args.headline}
             ></gs-mutation-comparison>
         </gs-app>
@@ -63,7 +68,7 @@ const Template: StoryObj<MutationComparisonProps> = {
 const dateTo = '2022-01-01';
 const dateFrom = '2021-01-01';
 
-export const Default: StoryObj<MutationComparisonProps> = {
+export const Default: StoryObj<Required<MutationComparisonProps>> = {
     ...Template,
     args: {
         variants: [
@@ -83,7 +88,8 @@ export const Default: StoryObj<MutationComparisonProps> = {
         ],
         sequenceType: 'nucleotide',
         views: ['table', 'venn'],
-        size: { width: '100%', height: '700px' },
+        width: '100%',
+        height: '700px',
         headline: 'Mutation comparison',
     },
     parameters: {
@@ -138,7 +144,7 @@ export const Default: StoryObj<MutationComparisonProps> = {
     },
 };
 
-export const VennDiagram: StoryObj<MutationComparisonProps> = {
+export const VennDiagram: StoryObj<Required<MutationComparisonProps>> = {
     ...Default,
     play: async ({ canvasElement, step }) => {
         const canvas = await withinShadowRoot(canvasElement, 'gs-mutation-comparison');

package/src/web-components/visualization/gs-mutation-comparison.tsx

@@ -1,15 +1,12 @@
 import { customElement, property } from 'lit/decorators.js';
 
-import {
-    MutationComparison,
-    type MutationComparisonVariant,
-    type View,
-} from '../../preact/mutationComparison/mutation-comparison';
-import { type SequenceType } from '../../types';
+import { MutationComparison, type MutationComparisonProps } from '../../preact/mutationComparison/mutation-comparison';
 import { type Equals, type Expect } from '../../utils/typeAssertions';
 import { PreactLitAdapterWithGridJsStyles } from '../PreactLitAdapterWithGridJsStyles';
 
 /**
+ * ## Context
+ *
  * This component allows to compare mutations between different variants.
  * A variant is defined by its LAPIS filter.
  *
@@ -35,6 +32,8 @@ import { PreactLitAdapterWithGridJsStyles } from '../PreactLitAdapterWithGridJsS
 @customElement('gs-mutation-comparison')
 export class MutationComparisonComponent extends PreactLitAdapterWithGridJsStyles {
     /**
+     * Required.
+     *
      * An array of variants to compare.
      *
      * The `lapisFilter` will be sent as is to LAPIS to filter the mutation data.
@@ -62,21 +61,26 @@ export class MutationComparisonComponent extends PreactLitAdapterWithGridJsStyle
     views: ('table' | 'venn')[] = ['table'];
 
     /**
-     * The size of the component.
+     * The width of the component.
      *
-     * If not set, the component will take the full width of its container with height 700px.
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
+     */
+    @property({ type: String })
+    width: string = '100%';
+
+    /**
+     * The height of the component.
      *
-     * The width and height should be a string with a unit in css style, e.g. '100%', '500px' or '50vh'.
-     * If the unit is %, the size will be relative to the container of the component.
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
      */
-    @property({ type: Object })
-    size: { width?: string; height?: string } | undefined = undefined;
+    @property({ type: String })
+    height: string = '700px';
 
     /**
      * The headline of the component. Set to an empty string to hide the headline.
      */
     @property({ type: String })
-    headline: string | undefined = 'Mutation comparison';
+    headline: string = 'Mutation comparison';
 
     override render() {
         return (
@@ -84,7 +88,8 @@ export class MutationComparisonComponent extends PreactLitAdapterWithGridJsStyle
                 variants={this.variants}
                 sequenceType={this.sequenceType}
                 views={this.views}
-                size={this.size}
+                width={this.width}
+                height={this.height}
                 headline={this.headline}
             />
         );
@@ -99,8 +104,12 @@ declare global {
 
 /* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars */
 type VariantsMatches = Expect<
-    Equals<typeof MutationComparisonComponent.prototype.variants, MutationComparisonVariant[]>
+    Equals<typeof MutationComparisonComponent.prototype.variants, MutationComparisonProps['variants']>
+>;
+type SequenceTypeMatches = Expect<
+    Equals<typeof MutationComparisonComponent.prototype.sequenceType, MutationComparisonProps['sequenceType']>
+>;
+type ViewsMatches = Expect<
+    Equals<typeof MutationComparisonComponent.prototype.views, MutationComparisonProps['views']>
 >;
-type SequenceTypeMatches = Expect<Equals<typeof MutationComparisonComponent.prototype.sequenceType, SequenceType>>;
-type ViewsMatches = Expect<Equals<typeof MutationComparisonComponent.prototype.views, View[]>>;
 /* eslint-enable @typescript-eslint/no-unused-vars, no-unused-vars */

package/src/web-components/visualization/gs-mutations.stories.ts

@@ -16,9 +16,12 @@ const codeExample = String.raw`
     variant='{ "country": "Switzerland", "pangoLineage": "B.1.1.7", "dateTo": "2022-01-01" }'
     sequenceType="nucleotide"
     views='["grid", "table", "insertions"]'
+    headline="Mutations"
+    width='100%'
+    height='700px'
 ></gs-mutations>`;
 
-const meta: Meta<MutationsProps> = {
+const meta: Meta<Required<MutationsProps>> = {
     title: 'Visualization/Mutations',
     component: 'gs-mutations',
     argTypes: {
@@ -31,14 +34,16 @@ const meta: Meta<MutationsProps> = {
             options: ['table', 'grid', 'insertions'],
             control: { type: 'check' },
         },
-        size: { control: 'object' },
+        width: { control: 'text' },
+        height: { control: 'text' },
         headline: { control: 'text' },
     },
     args: {
         variant: { country: 'Switzerland', pangoLineage: 'B.1.1.7', dateTo: '2022-01-01' },
         sequenceType: 'nucleotide',
         views: ['grid', 'table', 'insertions'],
-        size: { width: '100%', height: '700px' },
+        width: '100%',
+        height: '700px',
         headline: 'Mutations',
     },
     parameters: withComponentDocs({
@@ -53,21 +58,22 @@ const meta: Meta<MutationsProps> = {
 
 export default meta;
 
-const Template: StoryObj<MutationsProps> = {
+const Template: StoryObj<Required<MutationsProps>> = {
     render: (args) => html`
         <gs-app lapis="${LAPIS_URL}">
             <gs-mutations
                 .variant=${args.variant}
                 .sequenceType=${args.sequenceType}
                 .views=${args.views}
-                .size=${args.size}
+                .width=${args.width}
+                .height=${args.height}
                 .headline=${args.headline}
             ></gs-mutations>
         </gs-app>
     `,
 };
 
-export const Default: StoryObj<MutationsProps> = {
+export const Default: StoryObj<Required<MutationsProps>> = {
     ...Template,
     parameters: {
         fetchMock: {
@@ -104,7 +110,7 @@ export const Default: StoryObj<MutationsProps> = {
     },
 };
 
-export const OnTableTab: StoryObj<MutationsProps> = {
+export const OnTableTab: StoryObj<Required<MutationsProps>> = {
     ...Default,
     play: async ({ canvasElement }) => {
         const canvas = await withinShadowRoot(canvasElement, 'gs-mutations');
@@ -115,7 +121,7 @@ export const OnTableTab: StoryObj<MutationsProps> = {
     },
 };
 
-export const OnInsertionsTab: StoryObj<MutationsProps> = {
+export const OnInsertionsTab: StoryObj<Required<MutationsProps>> = {
     ...Default,
     play: async ({ canvasElement }) => {
         const canvas = await withinShadowRoot(canvasElement, 'gs-mutations');

package/src/web-components/visualization/gs-mutations.tsx

@@ -6,6 +6,8 @@ import type { Equals, Expect } from '../../utils/typeAssertions';
 import { PreactLitAdapterWithGridJsStyles } from '../PreactLitAdapterWithGridJsStyles';
 
 /**
+ * ## Context
+ *
  * This component displays mutations (substitutions, deletions and insertions) for a given variant.
  *
  * ## Views
@@ -33,6 +35,8 @@ import { PreactLitAdapterWithGridJsStyles } from '../PreactLitAdapterWithGridJsS
 @customElement('gs-mutations')
 export class MutationsComponent extends PreactLitAdapterWithGridJsStyles {
     /**
+     * Required.
+     *
      * The `variant` will be sent as is to LAPIS to filter the mutation data.
      * It must be a valid LAPIS filter object.
      */
@@ -52,21 +56,26 @@ export class MutationsComponent extends PreactLitAdapterWithGridJsStyles {
     views: ('table' | 'grid' | 'insertions')[] = ['table', 'grid'];
 
     /**
-     * The size of the component.
+     * The width of the component.
      *
-     * If not set, the component will take the full width of its container with height 700px.
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
+     */
+    @property({ type: String })
+    width: string = '100%';
+
+    /**
+     * The height of the component.
      *
-     * The width and height should be a string with a unit in css style, e.g. '100%', '500px' or '50vh'.
-     * If the unit is %, the size will be relative to the container of the component.
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
      */
-    @property({ type: Object })
-    size: { width?: string; height?: string } | undefined = undefined;
+    @property({ type: String })
+    height: string = '700px';
 
     /**
      * The headline of the component. Set to an empty string to hide the headline.
      */
     @property({ type: String })
-    headline: string | undefined = 'Mutations';
+    headline: string = 'Mutations';
 
     override render() {
         return (
@@ -74,7 +83,8 @@ export class MutationsComponent extends PreactLitAdapterWithGridJsStyles {
                 variant={this.variant}
                 sequenceType={this.sequenceType}
                 views={this.views}
-                size={this.size}
+                width={this.width}
+                height={this.height}
                 headline={this.headline}
             />
         );

package/src/web-components/visualization/gs-prevalence-over-time.stories.ts

@@ -16,15 +16,18 @@ import { withinShadowRoot } from '../withinShadowRoot.story';
 
 const codeExample = String.raw`
 <gs-prevalence-over-time
-    numerator='[{ "displayName": "EG", "country": "USA", "pangoLineage": "EG*" }, { "displayName": "JN.1", "country": "USA", "pangoLineage": "JN.1*" }]'
-    denominator='{ "country": "USA", "displayName": "All" }'
+    numerator='[{ "displayName": "EG", "lapisFilter": { "country": "USA", "pangoLineage": "EG*" }}, { "displayName": "JN.1", "lapisFilter": { "country": "USA", "pangoLineage": "JN.1*" }}]'
+    denominator='{ "country": "USA"}'
     granularity="month"
     smoothingWindow="0"
     views='["bar", "line", "bubble", "table"]'
     confidenceIntervalMethods='["wilson"]'
+    headline="Prevalence over time"
+    width='100%'
+    height='700px'
 ></gs-prevalence-over-time>`;
 
-const meta: Meta<PrevalenceOverTimeProps> = {
+const meta: Meta<Required<PrevalenceOverTimeProps>> = {
     title: 'Visualization/Prevalence over time',
     component: 'gs-prevalence-over-time',
     argTypes: {
@@ -43,7 +46,8 @@ const meta: Meta<PrevalenceOverTimeProps> = {
             options: ['wilson'],
             control: { type: 'check' },
         },
-        size: [{ control: 'object' }],
+        width: { control: 'text' },
+        height: { control: 'text' },
         headline: { control: 'text' },
     },
     parameters: withComponentDocs({
@@ -58,7 +62,7 @@ const meta: Meta<PrevalenceOverTimeProps> = {
 
 export default meta;
 
-const Template: StoryObj<PrevalenceOverTimeProps> = {
+const Template: StoryObj<Required<PrevalenceOverTimeProps>> = {
     render: (args) => html`
         <gs-app lapis="${LAPIS_URL}">
             <gs-prevalence-over-time
@@ -68,26 +72,28 @@ const Template: StoryObj<PrevalenceOverTimeProps> = {
                 .smoothingWindow=${args.smoothingWindow}
                 .views=${args.views}
                 .confidenceIntervalMethods=${args.confidenceIntervalMethods}
-                .size=${args.size}
+                .width=${args.width}
+                .height=${args.height}
                 .headline=${args.headline}
             ></gs-prevalence-over-time>
         </gs-app>
     `,
 };
 
-export const TwoVariants: StoryObj<PrevalenceOverTimeProps> = {
+export const TwoVariants: StoryObj<Required<PrevalenceOverTimeProps>> = {
     ...Template,
     args: {
         numerator: [
-            { displayName: 'EG', country: 'USA', pangoLineage: 'EG*', dateFrom: '2023-01-01' },
-            { displayName: 'JN.1', country: 'USA', pangoLineage: 'JN.1*', dateFrom: '2023-01-01' },
+            { displayName: 'EG', lapisFilter: { country: 'USA', pangoLineage: 'EG*', dateFrom: '2023-01-01' } },
+            { displayName: 'JN.1', lapisFilter: { country: 'USA', pangoLineage: 'JN.1*', dateFrom: '2023-01-01' } },
         ],
-        denominator: { country: 'USA', dateFrom: '2023-01-01', displayName: 'All' },
+        denominator: { country: 'USA', dateFrom: '2023-01-01' },
         granularity: 'month',
         smoothingWindow: 0,
         views: ['bar', 'line', 'bubble', 'table'],
         confidenceIntervalMethods: ['wilson'],
-        size: { width: '100%', height: '700px' },
+        width: '100%',
+        height: '700px',
         headline: 'Prevalence over time',
     },
     parameters: {
@@ -145,16 +151,20 @@ export const TwoVariants: StoryObj<PrevalenceOverTimeProps> = {
     },
 };
 
-export const OneVariant: StoryObj<PrevalenceOverTimeProps> = {
+export const OneVariant: StoryObj<Required<PrevalenceOverTimeProps>> = {
     ...Template,
     args: {
-        numerator: { displayName: 'EG', country: 'USA', pangoLineage: 'BA.2.86*', dateFrom: '2023-10-01' },
-        denominator: { country: 'USA', dateFrom: '2023-10-01', displayName: 'All' },
+        numerator: {
+            displayName: 'EG',
+            lapisFilter: { country: 'USA', pangoLineage: 'BA.2.86*', dateFrom: '2023-10-01' },
+        },
+        denominator: { country: 'USA', dateFrom: '2023-10-01' },
         granularity: 'day',
         smoothingWindow: 7,
         views: ['bar', 'line', 'bubble', 'table'],
         confidenceIntervalMethods: ['wilson'],
-        size: { width: '100%', height: '700px' },
+        width: '100%',
+        height: '700px',
         headline: 'Prevalence over time',
     },
     parameters: {
@@ -196,7 +206,7 @@ export const OneVariant: StoryObj<PrevalenceOverTimeProps> = {
     },
 };
 
-export const OneVariantOnLineTab: StoryObj<PrevalenceOverTimeProps> = {
+export const OneVariantOnLineTab: StoryObj<Required<PrevalenceOverTimeProps>> = {
     ...OneVariant,
     play: async ({ canvasElement }) => {
         const canvas = await withinShadowRoot(canvasElement, 'gs-prevalence-over-time');
@@ -207,7 +217,7 @@ export const OneVariantOnLineTab: StoryObj<PrevalenceOverTimeProps> = {
     },
 };
 
-export const OneVariantOnBubbleTab: StoryObj<PrevalenceOverTimeProps> = {
+export const OneVariantOnBubbleTab: StoryObj<Required<PrevalenceOverTimeProps>> = {
     ...OneVariant,
     play: async ({ canvasElement }) => {
         const canvas = await withinShadowRoot(canvasElement, 'gs-prevalence-over-time');
@@ -218,7 +228,7 @@ export const OneVariantOnBubbleTab: StoryObj<PrevalenceOverTimeProps> = {
     },
 };
 
-export const OneVariantOnTableTab: StoryObj<PrevalenceOverTimeProps> = {
+export const OneVariantOnTableTab: StoryObj<Required<PrevalenceOverTimeProps>> = {
     ...OneVariant,
     play: async ({ canvasElement }) => {
         const canvas = await withinShadowRoot(canvasElement, 'gs-prevalence-over-time');