@genspectrum/dashboard-components 0.1.4 → 0.2.0

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

@@ -0,0 +1,114 @@
+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.
+ *
+ * Validation of the input is performed according to the following rules:
+ *
+ * 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)
+ *     Example: S:614G, 614G, 614- or 614G
+ *
+ * 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)
+ *     Example: 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.
+     * Must be either
+     * - an array of strings of valid mutations.
+     * - an object with the keys `nucleotideMutations`, `aminoAcidMutations`, `nucleotideInsertions` and `aminoAcidInsertions` and corresponding string arrays.
+     */
+    @property()
+    initialValue:
+        {
+              nucleotideMutations: string[];
+              aminoAcidMutations: string[];
+              nucleotideInsertions: string[];
+              aminoAcidInsertions: string[];
+          }
+        | string[]
+        | undefined = undefined;
+
+    /**
+     * The size of the component.
+     *
+     * If not set, the component will take the full width of its container with height 700px.
+     *
+     * 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.
+     */
+    @property({ type: Object })
+    size: { width?: string; height?: string } | undefined = undefined;
+
+    override render() {
+        return (
+            <ReferenceGenomesAwaiter>
+                <MutationFilter initialValue={this.initialValue} size={this.size} />
+            </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}

@@ -3,17 +3,26 @@ import { expect, fn, userEvent, waitFor } from '@storybook/test';
 import type { Meta, StoryObj } from '@storybook/web-components';
 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 meta: Meta = {
+const codeExample = String.raw`
+<gs-text-input 
+    lapisField="host"
+    placeholderText="Enter host name"
+    initialValue="Homo sapiens"
+    width="50%">
+</gs-text-input>`;
+
+const meta: Meta<TextInputProps> = {
     title: 'Input/Text input',
     component: 'gs-text-input',
-    parameters: {
+    parameters: withComponentDocs({
         actions: {
             handles: ['gs-text-input-changed'],
         },
@@ -34,8 +43,36 @@ const meta: Meta = {
                 },
             ],
         },
+        componentDocs: {
+            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;
@@ -48,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>`;
@@ -56,6 +94,7 @@ export const Default: StoryObj<TextInputProps> = {
         lapisField: 'host',
         placeholderText: 'Enter host name',
         initialValue: 'Homo sapiens',
+        width: '100%',
     },
 };
 

package/src/web-components/input/gs-text-input.tsx

@@ -0,0 +1,73 @@
+import { customElement, property } from 'lit/decorators.js';
+
+import { TextInput } from '../../preact/textInput/text-input';
+import { PreactLitAdapter } from '../PreactLitAdapter';
+
+/**
+ *
+ * ## Context
+ *
+ * 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.
+ * The `details` of this event contain an object with the `lapisField` as key and the input value as value.
+ * Example:
+ * ```
+ * {
+ *  "host": "Homo sapiens"
+ * }
+ *  ```
+ */
+@customElement('gs-text-input')
+export class TextInputComponent extends PreactLitAdapter {
+    /**
+     * The initial value to use for this text input.
+     */
+    @property()
+    initialValue: string | undefined = '';
+
+    /**
+     * The Lapis field name to use for this text input.
+     */
+    @property()
+    lapisField = '';
+
+    /**
+     * The placeholder text to display in the input field.
+     */
+    @property()
+    placeholderText: string | undefined = '';
+
+    /**
+     * The width of the component.
+     *
+     * If not set, the component will take the full width of its container.
+     *
+     * The width should be a string with a unit in css style, e.g. '100%', '500px' or '50vw'.
+     * If the unit is %, the size will be relative to the container of the component.
+     */
+    @property({ type: Object })
+    width: string | undefined = undefined;
+
+    override render() {
+        return (
+            <TextInput
+                lapisField={this.lapisField}
+                placeholderText={this.placeholderText}
+                initialValue={this.initialValue}
+                width={this.width}
+            />
+        );
+    }
+}
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'gs-text-input': TextInputComponent;
+    }
+
+    interface HTMLElementEventMap {
+        'gs-text-input-changed': CustomEvent<Record<string, string>>;
+    }
+}

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/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,12 +6,12 @@ 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> = {
     title: 'Visualization/Aggregate',
-    component: 'gs-aggregate-component',
+    component: 'gs-aggregate',
     argTypes: {
         fields: [{ control: 'object' }],
         views: {
@@ -19,6 +19,7 @@ const meta: Meta<AggregateProps> = {
             control: { type: 'check' },
         },
         size: [{ control: 'object' }],
+        headline: { control: 'text' },
     },
     parameters: withComponentDocs({
         fetchMock: {
@@ -40,10 +41,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: `<gs-aggregate fields='["division", "host"]' filter='{"country": "USA"}' views='["table"]'></gs-aggregate>`,
         },
     }),
     tags: ['autodocs'],
@@ -54,12 +54,13 @@ export default meta;
 export const Table: StoryObj<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}
-            ></gs-aggregate-component>
+                .headline=${args.headline}
+            ></gs-aggregate>
         </gs-app>
     `,
     args: {
@@ -69,5 +70,6 @@ export const Table: StoryObj<AggregateProps> = {
             country: 'USA',
         },
         size: { width: '100%', height: '700px' },
+        headline: 'Aggregate',
     },
 };

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

@@ -11,7 +11,7 @@ import { PreactLitAdapterWithGridJsStyles } from '../PreactLitAdapterWithGridJsS
  *
  * It expects a list of fields to aggregate by and a filter to apply to the data.
  */
-@customElement('gs-aggregate-component')
+@customElement('gs-aggregate')
 export class AggregateComponent extends PreactLitAdapterWithGridJsStyles {
     /**
      * The fields to aggregate by.
@@ -46,8 +46,22 @@ export class AggregateComponent extends PreactLitAdapterWithGridJsStyles {
     @property({ type: Object })
     size: { width?: string; height?: string } | undefined = undefined;
 
+    /**
+     * The headline of the component. Set to an empty string to hide the headline.
+     */
+    @property({ type: String })
+    headline: string | undefined = 'Aggregate';
+
     override render() {
-        return <Aggregate fields={this.fields} views={this.views} filter={this.filter} size={this.size} />;
+        return (
+            <Aggregate
+                fields={this.fields}
+                views={this.views}
+                filter={this.filter}
+                size={this.size}
+                headline={this.headline}
+            />
+        );
     }
 }
 

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,15 @@ 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>`;
+></gs-mutation-comparison>`;
 
 const meta: Meta<MutationComparisonProps> = {
     title: 'Visualization/Mutation comparison',
-    component: 'gs-mutation-comparison-component',
+    component: 'gs-mutation-comparison',
     argTypes: {
         variants: { control: 'object' },
         sequenceType: {
@@ -32,10 +32,10 @@ const meta: Meta<MutationComparisonProps> = {
             control: { type: 'check' },
         },
         size: { control: 'object' },
+        headline: { control: 'text' },
     },
     parameters: withComponentDocs({
         componentDocs: {
-            tag: 'gs-mutation-comparison-component',
             opensShadowDom: true,
             expectsChildren: false,
             codeExample,
@@ -49,12 +49,13 @@ export default meta;
 const Template: StoryObj<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}
-            ></gs-mutation-comparison-component>
+                .headline=${args.headline}
+            ></gs-mutation-comparison>
         </gs-app>
     `,
 };
@@ -83,6 +84,7 @@ export const Default: StoryObj<MutationComparisonProps> = {
         sequenceType: 'nucleotide',
         views: ['table', 'venn'],
         size: { width: '100%', height: '700px' },
+        headline: 'Mutation comparison',
     },
     parameters: {
         fetchMock: {
@@ -124,7 +126,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,7 +141,7 @@ export const Default: StoryObj<MutationComparisonProps> = {
 export const VennDiagram: StoryObj<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());

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

@@ -32,7 +32,7 @@ import { PreactLitAdapterWithGridJsStyles } from '../PreactLitAdapterWithGridJsS
  * Thus, changing the proportion interval may change a mutations from being "common" between variant
  * to being "for one variant only".
  */
-@customElement('gs-mutation-comparison-component')
+@customElement('gs-mutation-comparison')
 export class MutationComparisonComponent extends PreactLitAdapterWithGridJsStyles {
     /**
      * An array of variants to compare.
@@ -72,6 +72,12 @@ export class MutationComparisonComponent extends PreactLitAdapterWithGridJsStyle
     @property({ type: Object })
     size: { width?: string; height?: string } | undefined = undefined;
 
+    /**
+     * The headline of the component. Set to an empty string to hide the headline.
+     */
+    @property({ type: String })
+    headline: string | undefined = 'Mutation comparison';
+
     override render() {
         return (
             <MutationComparison
@@ -79,6 +85,7 @@ export class MutationComparisonComponent extends PreactLitAdapterWithGridJsStyle
                 sequenceType={this.sequenceType}
                 views={this.views}
                 size={this.size}
+                headline={this.headline}
             />
         );
     }

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

@@ -2,14 +2,22 @@ import { expect, fireEvent, waitFor } from '@storybook/test';
 import type { Meta, StoryObj } from '@storybook/web-components';
 import { html } from 'lit';
 
-import './mutations-component';
+import './gs-mutations';
 import '../app';
+import { withComponentDocs } from '../../../.storybook/ComponentDocsBlock';
 import { LAPIS_URL, NUCLEOTIDE_INSERTIONS_ENDPOINT, NUCLEOTIDE_MUTATIONS_ENDPOINT } from '../../constants';
 import nucleotideInsertions from '../../preact/mutations/__mockData__/nucleotideInsertions.json';
 import nucleotideMutations from '../../preact/mutations/__mockData__/nucleotideMutations.json';
 import { type MutationsProps } from '../../preact/mutations/mutations';
 import { withinShadowRoot } from '../withinShadowRoot.story';
 
+const codeExample = String.raw`
+<gs-mutations
+    variant='{ "country": "Switzerland", "pangoLineage": "B.1.1.7", "dateTo": "2022-01-01" }'
+    sequenceType="nucleotide"
+    views='["grid", "table", "insertions"]'
+></gs-mutations>`;
+
 const meta: Meta<MutationsProps> = {
     title: 'Visualization/Mutations',
     component: 'gs-mutations',
@@ -24,7 +32,23 @@ const meta: Meta<MutationsProps> = {
             control: { type: 'check' },
         },
         size: { control: 'object' },
+        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' },
+        headline: 'Mutations',
     },
+    parameters: withComponentDocs({
+        componentDocs: {
+            opensShadowDom: true,
+            expectsChildren: false,
+            codeExample,
+        },
+    }),
+    tags: ['autodocs'],
 };
 
 export default meta;
@@ -32,24 +56,19 @@ export default meta;
 const Template: StoryObj<MutationsProps> = {
     render: (args) => html`
         <gs-app lapis="${LAPIS_URL}">
-            <gs-mutations-component
+            <gs-mutations
                 .variant=${args.variant}
                 .sequenceType=${args.sequenceType}
                 .views=${args.views}
                 .size=${args.size}
-            ></gs-mutations-component>
+                .headline=${args.headline}
+            ></gs-mutations>
         </gs-app>
     `,
 };
 
 export const Default: StoryObj<MutationsProps> = {
     ...Template,
-    args: {
-        variant: { country: 'Switzerland', pangoLineage: 'B.1.1.7', dateTo: '2022-01-01' },
-        sequenceType: 'nucleotide',
-        views: ['grid', 'table', 'insertions'],
-        size: { width: '100%', height: '700px' },
-    },
     parameters: {
         fetchMock: {
             mocks: [
@@ -88,7 +107,7 @@ export const Default: StoryObj<MutationsProps> = {
 export const OnTableTab: StoryObj<MutationsProps> = {
     ...Default,
     play: async ({ canvasElement }) => {
-        const canvas = await withinShadowRoot(canvasElement, 'gs-mutations-component');
+        const canvas = await withinShadowRoot(canvasElement, 'gs-mutations');
 
         await waitFor(() => expect(canvas.getByRole('button', { name: 'Table' })).toBeInTheDocument());
 
@@ -99,7 +118,7 @@ export const OnTableTab: StoryObj<MutationsProps> = {
 export const OnInsertionsTab: StoryObj<MutationsProps> = {
     ...Default,
     play: async ({ canvasElement }) => {
-        const canvas = await withinShadowRoot(canvasElement, 'gs-mutations-component');
+        const canvas = await withinShadowRoot(canvasElement, 'gs-mutations');
 
         await waitFor(() => expect(canvas.getByRole('button', { name: 'Insertions' })).toBeInTheDocument());