@genspectrum/dashboard-components 0.1.5 → 0.3.0

package/src/web-components/input/{mutation-filter-component.stories.ts → gs-mutation-filter.stories.ts}

@@ -8,9 +8,14 @@ import { LAPIS_URL } from '../../constants';
 import '../app';
 import { type MutationFilterProps } from '../../preact/mutationFilter/mutation-filter';
 import { withinShadowRoot } from '../withinShadowRoot.story';
-import './mutation-filter-component';
+import './gs-mutation-filter';
 
-const codeExample = String.raw`<gs-mutation-filter initialValue='["A123T"]'></gs-mutation-filter>`;
+const codeExample = String.raw`
+<gs-mutation-filter 
+    initialValue='["A123T"]'
+    width='100%'
+    height='6.5rem'
+></gs-mutation-filter>`;
 
 const meta: Meta<MutationFilterProps> = {
     title: 'Input/Mutation filter',
@@ -21,12 +26,20 @@ const meta: Meta<MutationFilterProps> = {
         },
         fetchMock: {},
         componentDocs: {
-            tag: 'gs-mutation-filter',
             opensShadowDom: true,
             expectsChildren: false,
             codeExample,
         },
     }),
+    argTypes: {
+        initialValue: {
+            control: {
+                type: 'object',
+            },
+        },
+        width: { control: 'text' },
+        height: { control: 'text' },
+    },
     decorators: [withActions],
     tags: ['autodocs'],
 };
@@ -37,12 +50,18 @@ const Template: StoryObj<MutationFilterProps> = {
     render: (args) => {
         return html` <gs-app lapis="${LAPIS_URL}">
             <div class="max-w-screen-lg">
-                <gs-mutation-filter .initialValue=${args.initialValue}></gs-mutation-filter>
+                <gs-mutation-filter
+                    .initialValue=${args.initialValue}
+                    .width=${args.width}
+                    .height=${args.height}
+                ></gs-mutation-filter>
             </div>
         </gs-app>`;
     },
     args: {
         initialValue: [],
+        width: '100%',
+        height: '3rem',
     },
 };
 

package/src/web-components/input/gs-mutation-filter.tsx

@@ -0,0 +1,126 @@
+import { customElement, property } from 'lit/decorators.js';
+
+import { ReferenceGenomesAwaiter } from '../../preact/components/ReferenceGenomesAwaiter';
+import {
+    MutationFilter,
+    type MutationFilterProps,
+    type SelectedMutationFilterStrings,
+} from '../../preact/mutationFilter/mutation-filter';
+import type { Equals, Expect } from '../../utils/typeAssertions';
+import { PreactLitAdapter } from '../PreactLitAdapter';
+
+/**
+ * ## Context
+ * This component provides an input field to specify filters for nucleotide and amino acid mutations and insertions.
+ *
+ * Input values have to be provided one at a time and submitted by pressing the Enter key or by clicking the '+' button.
+ * After submission, the component validates the input and fires an event with the selected mutations.
+ * All previously selected mutations are displayed at the input field and added to the event.
+ * Users can remove a mutation by clicking the 'x' button next to the mutation.
+ *
+ * ## Input Validation
+ *
+ * Validation of the input is performed according to the following rules:
+ *
+ * ### Mutations
+ *
+ * Mutations have to conform to the following format: `<gene/segment>:<symbol at reference><position><Substituted symbol/Deletion>`
+ * - Gene/segment: The gene or segment where the mutation occurs. Must be contained in the reference genome.
+ *   (Optional for elements with only one gene/segment)
+ * - Symbol at reference: The symbol at the reference position. (Optional)
+ * - Position: The position of the mutation. (Required)
+ * - Substituted symbol/Deletion: The substituted symbol or '-' for a deletion. (Required)
+ *
+ * Examples: `S:614G`, `614G`, `614-`, `614G`
+ *
+ * ### Insertions
+ *
+ * Insertions have to conform to the following format: `ins_<gene/segment>:<position>:<Inserted symbols>`
+ * - Gene/segment: The gene or segment where the insertion occurs. Must be contained in the reference genome.
+ *   (Optional for elements with only one gene/segment)
+ * - Position: The position of the insertion. (Required)
+ * - Inserted symbols: The symbols that are inserted. (Required)
+ *
+ * Examples: `ins_S:614:G`, `ins_614:G`
+ *
+ * @fires {CustomEvent<{
+ *      nucleotideMutations: string[],
+ *      aminoAcidMutations: string[],
+ *      nucleotideInsertions: string[],
+ *      aminoAcidInsertions: string[]
+ *  }>} gs-mutation-filter-changed
+ * Fired when:
+ * - The user has submitted a valid mutation or insertion
+ * - The user has removed a mutation or insertion
+ *
+ * @fires {CustomEvent<{
+ *      nucleotideMutations: string[],
+ *      aminoAcidMutations: string[],
+ *      nucleotideInsertions: string[],
+ *      aminoAcidInsertions: string[]
+ *  }>} gs-mutation-filter-on-blur
+ * Fired when:
+ * - the mutation filter has lost focus
+ * Contains the selected mutations in the format
+ */
+@customElement('gs-mutation-filter')
+export class MutationFilterComponent extends PreactLitAdapter {
+    // prettier-ignore
+    // The multiline union type must not start with `|` because it looks weird in the Storybook docs
+    /**
+     * The initial value to use for this mutation filter.
+     * All values provided must be valid mutations or insertions.
+     * Invalid values will be ignored.
+     */
+    @property()
+    initialValue:
+        {
+            nucleotideMutations: string[];
+            aminoAcidMutations: string[];
+            nucleotideInsertions: string[];
+            aminoAcidInsertions: string[];
+        }
+        | string[]
+        | undefined = undefined;
+
+    /**
+     * The width of the component.
+     *
+     * 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.
+     *
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
+     */
+    @property({ type: String })
+    height: string = '6.5rem';
+
+    override render() {
+        return (
+            <ReferenceGenomesAwaiter>
+                <MutationFilter initialValue={this.initialValue} width={this.width} height={this.height} />
+            </ReferenceGenomesAwaiter>
+        );
+    }
+}
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'gs-mutation-filter': MutationFilterComponent;
+    }
+
+    interface HTMLElementEventMap {
+        'gs-mutation-filter-changed': CustomEvent<SelectedMutationFilterStrings>;
+        'gs-mutation-filter-on-blur': CustomEvent<SelectedMutationFilterStrings>;
+    }
+}
+
+/* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars */
+type InitialValueMatches = Expect<
+    Equals<typeof MutationFilterComponent.prototype.initialValue, MutationFilterProps['initialValue']>
+>;
+/* eslint-enable @typescript-eslint/no-unused-vars, no-unused-vars */

package/src/web-components/input/{text-input-component.stories.ts → gs-text-input.stories.ts}

@@ -6,15 +6,20 @@ import { html } from 'lit';
 import { withComponentDocs } from '../../../.storybook/ComponentDocsBlock';
 import { AGGREGATED_ENDPOINT, LAPIS_URL } from '../../constants';
 import '../app';
-import './text-input-component';
+import './gs-text-input';
 import data from '../../preact/textInput/__mockData__/aggregated_hosts.json';
 import type { TextInputProps } from '../../preact/textInput/text-input';
 import { withinShadowRoot } from '../withinShadowRoot.story';
 
 const codeExample = String.raw`
-<gs-text-input lapisField="host" placeholderText="Enter host name" initialValue="Homo sapiens"></gs-text-input>`;
+<gs-text-input 
+    lapisField="host"
+    placeholderText="Enter host name"
+    initialValue="Homo sapiens"
+    width="50%">
+</gs-text-input>`;
 
-const meta: Meta<TextInputProps> = {
+const meta: Meta<Required<TextInputProps>> = {
     title: 'Input/Text input',
     component: 'gs-text-input',
     parameters: withComponentDocs({
@@ -39,19 +44,40 @@ const meta: Meta<TextInputProps> = {
             ],
         },
         componentDocs: {
-            tag: 'gs-text-input',
             opensShadowDom: true,
             expectsChildren: false,
             codeExample,
         },
     }),
+    argTypes: {
+        lapisField: {
+            control: {
+                type: 'text',
+            },
+        },
+        placeholderText: {
+            control: {
+                type: 'text',
+            },
+        },
+        initialValue: {
+            control: {
+                type: 'text',
+            },
+        },
+        width: {
+            control: {
+                type: 'text',
+            },
+        },
+    },
     decorators: [withActions],
     tags: ['autodocs'],
 };
 
 export default meta;
 
-export const Default: StoryObj<TextInputProps> = {
+export const Default: StoryObj<Required<TextInputProps>> = {
     render: (args) => {
         return html` <gs-app lapis="${LAPIS_URL}">
             <div class="max-w-screen-lg">
@@ -59,6 +85,7 @@ export const Default: StoryObj<TextInputProps> = {
                     .lapisField=${args.lapisField}
                     .placeholderText=${args.placeholderText}
                     .initialValue=${args.initialValue}
+                    .width=${args.width}
                 ></gs-text-input>
             </div>
         </gs-app>`;
@@ -67,10 +94,11 @@ export const Default: StoryObj<TextInputProps> = {
         lapisField: 'host',
         placeholderText: 'Enter host name',
         initialValue: 'Homo sapiens',
+        width: '100%',
     },
 };
 
-export const FiresEvent: StoryObj<TextInputProps> = {
+export const FiresEvent: StoryObj<Required<TextInputProps>> = {
     ...Default,
     play: async ({ canvasElement, step }) => {
         const canvas = await withinShadowRoot(canvasElement, 'gs-text-input');

package/src/web-components/input/{text-input-component.tsx → gs-text-input.tsx}

@@ -7,7 +7,7 @@ import { PreactLitAdapter } from '../PreactLitAdapter';
  *
  * ## Context
  *
- * This component provides a text input field to specify filters for arbitrary fields of this Lapis instance.
+ * This component provides a text input field to specify filters for arbitrary fields of this LAPIS instance.
  *
  * @fires {CustomEvent<Record<string, string>>} gs-text-input-changed
  * Fired when the input field is changed.
@@ -25,10 +25,13 @@ export class TextInputComponent extends PreactLitAdapter {
      * The initial value to use for this text input.
      */
     @property()
-    initialValue: string | undefined = '';
+    initialValue: string = '';
 
     /**
-     * The Lapis field name to use for this text input.
+     * Required.
+     *
+     * The LAPIS field name to use for this text input.
+     * The field must exist on this LAPIS instance.
      */
     @property()
     lapisField = '';
@@ -37,7 +40,15 @@ export class TextInputComponent extends PreactLitAdapter {
      * The placeholder text to display in the input field.
      */
     @property()
-    placeholderText: string | undefined = '';
+    placeholderText: string = '';
+
+    /**
+     * The width of the component.
+     *
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
+     */
+    @property({ type: String })
+    width: string = '100%';
 
     override render() {
         return (
@@ -45,6 +56,7 @@ export class TextInputComponent extends PreactLitAdapter {
                 lapisField={this.lapisField}
                 placeholderText={this.placeholderText}
                 initialValue={this.initialValue}
+                width={this.width}
             />
         );
     }

package/src/web-components/input/index.ts

@@ -1,4 +1,4 @@
-export { DateRangeSelectorComponent } from './date-range-selector-component';
-export { LocationFilterComponent } from './location-filter-component';
-export { TextInputComponent } from './text-input-component';
-export { MutationFilterComponent } from './mutation-filter-component';
+export { DateRangeSelectorComponent } from './gs-date-range-selector';
+export { LocationFilterComponent } from './gs-location-filter';
+export { TextInputComponent } from './gs-text-input';
+export { MutationFilterComponent } from './gs-mutation-filter';

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/data_visualization_statistical_analysis.mdx

@@ -0,0 +1,26 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title='Visualization/Data Visualization and Statistical Analysis' />
+
+# Data Visualization and Statistical Analysis
+
+## Scales
+
+On most plots, users can select the y-axis scaling through a dropdown.
+They can choose between linear, logarithmic and logistic scaling.
+By default, it is set to a linear scale.
+
+In general, for each scale the displayed height of a value is calculated by applying the corresponding scale function.
+
+-   Linear: `value`
+-   Logarithmic: `ln(value)`
+-   Logistic: `ln(value / (1 - value))`
+
+## Confidence Intervals
+
+On bar and line plots, users can choose to display confidence intervals.
+For line plots, this is done by shading the area between the upper and lower bounds.
+For bar plots, this is done by adding error bars to the top of each bar.
+
+Currently, only one method is available for calculating the confidence intervals:
+the [wilson score interval](https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval) with a confidence level of 95%.

package/src/web-components/{display/aggregate-component.stories.ts → visualization/gs-aggregate.stories.ts}

@@ -6,19 +6,30 @@ import { AGGREGATED_ENDPOINT, LAPIS_URL } from '../../constants';
 import aggregatedData from '../../preact/aggregatedData/__mockData__/aggregated.json';
 import type { AggregateProps } from '../../preact/aggregatedData/aggregate';
 
-import './aggregate-component';
+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-component',
+    component: 'gs-aggregate',
     argTypes: {
         fields: [{ control: 'object' }],
         views: {
             options: ['table'],
             control: { type: 'check' },
         },
-        size: [{ control: 'object' }],
+        width: { control: 'text' },
+        height: { control: 'text' },
         headline: { control: 'text' },
     },
     parameters: withComponentDocs({
@@ -41,10 +52,9 @@ const meta: Meta<AggregateProps> = {
             ],
         },
         componentDocs: {
-            tag: 'gs-aggregate-component',
             opensShadowDom: true,
             expectsChildren: false,
-            codeExample: `<gs-aggregate-component fields='["division", "host"]' filter='{"country": "USA"}' views='["table"]'></gs-aggregate-component>`,
+            codeExample,
         },
     }),
     tags: ['autodocs'],
@@ -52,16 +62,17 @@ 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-component
+            <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-component>
+            ></gs-aggregate>
         </gs-app>
     `,
     args: {
@@ -70,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

@@ -0,0 +1,88 @@
+import { customElement, property } from 'lit/decorators.js';
+
+import { Aggregate, type View } from '../../preact/aggregatedData/aggregate';
+import { type LapisFilter } from '../../types';
+import { PreactLitAdapterWithGridJsStyles } from '../PreactLitAdapterWithGridJsStyles';
+
+/**
+ * ## Context
+ *
+ * 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.
+ *
+ * ## 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[] = [];
+
+    /**
+     * 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 width of the component.
+     *
+     * 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.
+     *
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
+     */
+    @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 = 'Aggregate';
+
+    override render() {
+        return (
+            <Aggregate
+                fields={this.fields}
+                views={this.views}
+                filter={this.filter}
+                width={this.width}
+                height={this.height}
+                headline={this.headline}
+            />
+        );
+    }
+}
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'gs-aggregate-component': AggregateComponent;
+    }
+}

package/src/web-components/{display/mutation-comparison-component.stories.ts → visualization/gs-mutation-comparison.stories.ts}

@@ -2,7 +2,7 @@ import { expect, fireEvent, waitFor } from '@storybook/test';
 import type { Meta, StoryObj } from '@storybook/web-components';
 import { html } from 'lit';
 
-import './mutation-comparison-component';
+import './gs-mutation-comparison';
 import '../app';
 import { withComponentDocs } from '../../../.storybook/ComponentDocsBlock';
 import { LAPIS_URL, NUCLEOTIDE_MUTATIONS_ENDPOINT } from '../../constants';
@@ -12,15 +12,18 @@ import { type MutationComparisonProps } from '../../preact/mutationComparison/mu
 import { withinShadowRoot } from '../withinShadowRoot.story';
 
 const codeExample = String.raw`
-<gs-mutation-comparison-component
+<gs-mutation-comparison
     variants='[{ "displayName": "variant1", "lapisFilter": { "country": "Switzerland" }}, { "displayName": "variant2", "lapisFilter": { "country": "Germany" }}]'
     sequenceType="nucleotide"
     views='["table", "venn"]'
-></gs-mutation-comparison-component>`;
+    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-component',
+    component: 'gs-mutation-comparison',
     argTypes: {
         variants: { control: 'object' },
         sequenceType: {
@@ -31,12 +34,12 @@ const meta: Meta<MutationComparisonProps> = {
             options: ['table', 'venn'],
             control: { type: 'check' },
         },
-        size: { control: 'object' },
+        width: { control: 'text' },
+        height: { control: 'text' },
         headline: { control: 'text' },
     },
     parameters: withComponentDocs({
         componentDocs: {
-            tag: 'gs-mutation-comparison-component',
             opensShadowDom: true,
             expectsChildren: false,
             codeExample,
@@ -47,16 +50,17 @@ 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-component
+            <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-component>
+            ></gs-mutation-comparison>
         </gs-app>
     `,
 };
@@ -64,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: [
@@ -84,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: {
@@ -127,7 +132,7 @@ export const Default: StoryObj<MutationComparisonProps> = {
         },
     },
     play: async ({ canvasElement, step }) => {
-        const canvas = await withinShadowRoot(canvasElement, 'gs-mutation-comparison-component');
+        const canvas = await withinShadowRoot(canvasElement, 'gs-mutation-comparison');
 
         await step('Min and max proportions should be 50% and 100%', async () => {
             const minInput = () => canvas.getAllByLabelText('%')[0];
@@ -139,10 +144,10 @@ 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-component');
+        const canvas = await withinShadowRoot(canvasElement, 'gs-mutation-comparison');
 
         await step('Switch to Venn diagram view', async () => {
             await waitFor(() => expect(canvas.getByRole('button', { name: 'Venn' })).toBeInTheDocument());