@genspectrum/dashboard-components 0.1.3 → 0.1.5

package/src/web-components/app.stories.ts

@@ -0,0 +1,129 @@
+import { consume } from '@lit/context';
+import { withActions } from '@storybook/addon-actions/decorator';
+import { expect, waitFor, within } from '@storybook/test';
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { html, LitElement } from 'lit';
+import { customElement } from 'lit/decorators.js';
+
+import './app';
+
+import { lapisContext } from './lapis-context';
+import { referenceGenomeContext } from './reference-genome-context';
+import { withComponentDocs } from '../../.storybook/ComponentDocsBlock';
+import { LAPIS_URL, REFERENCE_GENOME_ENDPOINT } from '../constants';
+import type { ReferenceGenome } from '../lapisApi/ReferenceGenome';
+import referenceGenome from '../lapisApi/__mockData__/referenceGenome.json';
+
+const codeExample = String.raw`
+<gs-app lapis="https://url.to.lapis">
+    <p>Your application code goes here.</p> 
+</gs-app>`;
+
+const meta: Meta = {
+    title: 'Wrapper/App',
+    component: 'gs-app',
+    parameters: withComponentDocs({
+        fetchMock: {},
+        componentDocs: {
+            tag: 'gs-app',
+            opensShadowDom: false,
+            expectsChildren: true,
+            codeExample,
+        },
+    }),
+    decorators: [withActions],
+    tags: ['autodocs'],
+};
+
+export default meta;
+
+const Template: StoryObj<{ lapis: string }> = {
+    render: (args) => {
+        return html` <gs-app lapis="${args.lapis}">
+            <gs-app-display></gs-app-display>
+        </gs-app>`;
+    },
+    args: {
+        lapis: LAPIS_URL,
+    },
+};
+
+export const Default: StoryObj<{ lapis: string }> = {
+    ...Template,
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+
+        await waitFor(() => {
+            expect(canvas.getByText(LAPIS_URL)).toBeVisible();
+            expect(canvas.getByText('"name": "ORF1a",', { exact: false })).toBeVisible();
+        });
+    },
+};
+
+export const DelayFetchingReferenceGenome: StoryObj<{ lapis: string }> = {
+    ...Template,
+    parameters: {
+        fetchMock: {
+            mocks: [
+                {
+                    matcher: {
+                        name: 'referenceGenome',
+                        url: REFERENCE_GENOME_ENDPOINT,
+                    },
+                    response: {
+                        status: 200,
+                        body: referenceGenome,
+                    },
+                    options: {
+                        delay: 5000,
+                    },
+                },
+            ],
+        },
+    },
+};
+
+export const FailsToFetchReferenceGenome: StoryObj<{ lapis: string }> = {
+    ...Template,
+    args: {
+        lapis: 'definitely-not-a-valid-url',
+    },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+
+        await waitFor(() => {
+            expect(canvas.getByText('Error')).toBeVisible();
+        });
+    },
+};
+
+@customElement('gs-app-display')
+// eslint-disable-next-line no-unused-vars,@typescript-eslint/no-unused-vars -- it is used in the story above
+class AppDisplay extends LitElement {
+    @consume({ context: lapisContext })
+    lapis: string = '';
+
+    @consume({ context: referenceGenomeContext, subscribe: true })
+    referenceGenome: ReferenceGenome = {
+        nucleotideSequences: [],
+        genes: [],
+    };
+
+    override render() {
+        return html`
+            <h1 class="text-xl font-bold">Dummy component</h1>
+            <p>
+                What you can see here is a dummy component that displays the values of the wrapping "gs-app". Actually
+                "gs-app" doesn't display anything.
+            </p>
+            <h2 class="text-lg font-bold">LAPIS URL</h2>
+            <p>${this.lapis}</p>
+            <h2 class="text-lg font-bold">Reference genomes</h2>
+            <pre><code>${JSON.stringify(this.referenceGenome, null, 2)}</code></pre>
+        `;
+    }
+
+    override createRenderRoot() {
+        return this;
+    }
+}

package/src/web-components/app.ts

@@ -8,18 +8,43 @@ import { referenceGenomeContext } from './reference-genome-context';
 import { type ReferenceGenome } from '../lapisApi/ReferenceGenome';
 import { fetchReferenceGenome } from '../lapisApi/lapisApi';
 
+/**
+ * ## Context
+ *
+ * This component provides the main application context.
+ * All other `gs-*` components must be (possibly nested) children of this component.
+ * It makes use of the [Lit Context](https://lit.dev/docs/data/context/) to
+ * - provide the URL to the LAPIS instance to all its children
+ * - fetch the reference genomes from LAPIS and provide it to all its children
+ *
+ * This will show an error message if the reference genome cannot be fetched
+ * (e.g., due to an invalid LAPIS URL).
+ *
+ * ## Shadow DOM
+ *
+ * This component does __not__ use a shadow DOM. Children of this component will be rendered directly in the light DOM.
+ */
 @customElement('gs-app')
 export class App extends LitElement {
+    /**
+     * The URL of the LAPIS instance that all children of this component will use.
+     */
     @provide({ context: lapisContext })
     @property()
     lapis: string = '';
 
+    /**
+     * @internal
+     */
     @provide({ context: referenceGenomeContext })
     referenceGenome: ReferenceGenome = {
         nucleotideSequences: [],
         genes: [],
     };
 
+    /**
+     * @internal
+     */
     private updateReferenceGenome = new Task(this, {
         task: async () => {
             this.referenceGenome = await fetchReferenceGenome(this.lapis);
@@ -29,13 +54,9 @@ export class App extends LitElement {
 
     override render() {
         return this.updateReferenceGenome.render({
-            complete: () => {
-                return html` <slot></slot>`;
-            },
+            complete: () => html` <slot></slot>`,
             error: () => html`<p>Error</p>`, // TODO(#143): Add more advanced error handling
-            pending: () => {
-                return html`<p>Loading...</p>`;
-            },
+            pending: () => html` <p>Loading reference genomes...</p> `,
         });
     }
 

package/src/web-components/display/aggregate-component.stories.ts

@@ -1,9 +1,11 @@
 import { type Meta, type StoryObj } from '@storybook/web-components';
 import { html } from 'lit';
 
+import { withComponentDocs } from '../../../.storybook/ComponentDocsBlock';
 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 '../app';
 
@@ -16,8 +18,10 @@ const meta: Meta<AggregateProps> = {
             options: ['table'],
             control: { type: 'check' },
         },
+        size: [{ control: 'object' }],
+        headline: { control: 'text' },
     },
-    parameters: {
+    parameters: withComponentDocs({
         fetchMock: {
             mocks: [
                 {
@@ -36,22 +40,29 @@ 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>`,
+        },
+    }),
+    tags: ['autodocs'],
 };
 
 export default meta;
 
 export const Table: StoryObj<AggregateProps> = {
     render: (args) => html`
-        <div class="w-11/12 h-11/12">
-            <gs-app lapis="${LAPIS_URL}">
-                <gs-aggregate-component
-                    .fields=${args.fields}
-                    .filter=${args.filter}
-                    .views=${args.views}
-                ></gs-aggregate-component>
-            </gs-app>
-        </div>
+        <gs-app lapis="${LAPIS_URL}">
+            <gs-aggregate-component
+                .fields=${args.fields}
+                .filter=${args.filter}
+                .views=${args.views}
+                .size=${args.size}
+                .headline=${args.headline}
+            ></gs-aggregate-component>
+        </gs-app>
     `,
     args: {
         fields: ['division', 'host'],
@@ -59,5 +70,7 @@ export const Table: StoryObj<AggregateProps> = {
         filter: {
             country: 'USA',
         },
+        size: { width: '100%', height: '700px' },
+        headline: 'Aggregate',
     },
 };

package/src/web-components/display/aggregate-component.tsx

@@ -5,10 +5,6 @@ import { type LapisFilter } from '../../types';
 import { PreactLitAdapterWithGridJsStyles } from '../PreactLitAdapterWithGridJsStyles';
 
 /**
- * ## Tag
- *
- * `gs-aggregate-component`
- *
  * ## Context
  *
  * This component displays aggregated data, which can provide an overview of the underlying data.
@@ -39,8 +35,33 @@ export class AggregateComponent extends PreactLitAdapterWithGridJsStyles {
     @property({ type: Object })
     filter: LapisFilter = {};
 
+    /**
+     * 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;
+
+    /**
+     * 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} />;
+        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

@@ -4,12 +4,20 @@ import { html } from 'lit';
 
 import './mutation-comparison-component';
 import '../app';
+import { withComponentDocs } from '../../../.storybook/ComponentDocsBlock';
 import { LAPIS_URL, NUCLEOTIDE_MUTATIONS_ENDPOINT } from '../../constants';
 import nucleotideMutationsOtherVariant from '../../preact/mutationComparison/__mockData__/nucleotideMutationsOtherVariant.json';
 import nucleotideMutationsSomeVariant from '../../preact/mutationComparison/__mockData__/nucleotideMutationsSomeVariant.json';
 import { type MutationComparisonProps } from '../../preact/mutationComparison/mutation-comparison';
 import { withinShadowRoot } from '../withinShadowRoot.story';
 
+const codeExample = String.raw`
+<gs-mutation-comparison-component
+    variants='[{ "displayName": "variant1", "lapisFilter": { "country": "Switzerland" }}, { "displayName": "variant2", "lapisFilter": { "country": "Germany" }}]'
+    sequenceType="nucleotide"
+    views='["table", "venn"]'
+></gs-mutation-comparison-component>`;
+
 const meta: Meta<MutationComparisonProps> = {
     title: 'Visualization/Mutation comparison',
     component: 'gs-mutation-comparison-component',
@@ -23,22 +31,33 @@ const meta: Meta<MutationComparisonProps> = {
             options: ['table', 'venn'],
             control: { type: 'check' },
         },
+        size: { control: 'object' },
+        headline: { control: 'text' },
     },
+    parameters: withComponentDocs({
+        componentDocs: {
+            tag: 'gs-mutation-comparison-component',
+            opensShadowDom: true,
+            expectsChildren: false,
+            codeExample,
+        },
+    }),
+    tags: ['autodocs'],
 };
 
 export default meta;
 
 const Template: StoryObj<MutationComparisonProps> = {
     render: (args) => html`
-        <div class="w-11/12 h-11/12">
-            <gs-app lapis="${LAPIS_URL}">
-                <gs-mutation-comparison-component
-                    .variants=${args.variants}
-                    .sequenceType=${args.sequenceType}
-                    .views=${args.views}
-                ></gs-mutation-comparison-component>
-            </gs-app>
-        </div>
+        <gs-app lapis="${LAPIS_URL}">
+            <gs-mutation-comparison-component
+                .variants=${args.variants}
+                .sequenceType=${args.sequenceType}
+                .views=${args.views}
+                .size=${args.size}
+                .headline=${args.headline}
+            ></gs-mutation-comparison-component>
+        </gs-app>
     `,
 };
 
@@ -65,6 +84,8 @@ export const Default: StoryObj<MutationComparisonProps> = {
         ],
         sequenceType: 'nucleotide',
         views: ['table', 'venn'],
+        size: { width: '100%', height: '700px' },
+        headline: 'Mutation comparison',
     },
     parameters: {
         fetchMock: {
@@ -124,9 +145,9 @@ export const VennDiagram: StoryObj<MutationComparisonProps> = {
         const canvas = await withinShadowRoot(canvasElement, 'gs-mutation-comparison-component');
 
         await step('Switch to Venn diagram view', async () => {
-            await waitFor(() => expect(canvas.getByLabelText('Venn', { selector: 'input' })).toBeInTheDocument());
+            await waitFor(() => expect(canvas.getByRole('button', { name: 'Venn' })).toBeInTheDocument());
 
-            await fireEvent.click(canvas.getByLabelText('Venn', { selector: 'input' }));
+            await fireEvent.click(canvas.getByRole('button', { name: 'Venn' }));
 
             await waitFor(() =>
                 expect(

package/src/web-components/display/mutation-comparison-component.tsx

@@ -6,21 +6,88 @@ import {
     type View,
 } from '../../preact/mutationComparison/mutation-comparison';
 import { type SequenceType } from '../../types';
+import { type Equals, type Expect } from '../../utils/typeAssertions';
 import { PreactLitAdapterWithGridJsStyles } from '../PreactLitAdapterWithGridJsStyles';
 
+/**
+ * This component allows to compare mutations between different variants.
+ * A variant is defined by its LAPIS filter.
+ *
+ * It only shows substitutions and deletions, it does not show insertions.
+ *
+ * ## Views
+ *
+ * ### Table View
+ *
+ * The table view shows mutations
+ * and the proportions with which the mutation occurs in the respective variant.
+ * It only shows mutations that are present in at least one of the variants
+ * and where the proportion is within the selected proportion interval for at least one variant.
+ *
+ * ### Venn View
+ *
+ * The Venn view shows the overlap of mutations between the variants in a Venn diagram.
+ * A variant is considered to have a certain mutation,
+ * if the proportion of the mutation in the variant is within the selected proportion interval.
+ * 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')
 export class MutationComparisonComponent extends PreactLitAdapterWithGridJsStyles {
+    /**
+     * An array of variants to compare.
+     *
+     * The `lapisFilter` will be sent as is to LAPIS to filter the mutation data.
+     * It must be a valid LAPIS filter object.
+     *
+     * The `displayName` will be used as the label for the variant in the views.
+     * It should be human-readable.
+     */
     @property({ type: Array })
-    variants: MutationComparisonVariant[] = [];
+    variants: {
+        lapisFilter: Record<string, string | number | null | boolean>;
+        displayName: string;
+    }[] = [];
 
+    /**
+     * The type of the sequence for which the mutations should be shown.
+     */
     @property({ type: String })
-    sequenceType: SequenceType = 'nucleotide';
+    sequenceType: 'nucleotide' | 'amino acid' = 'nucleotide';
 
+    /**
+     * A list of tabs with views that this component should provide.
+     */
     @property({ type: Array })
-    views: View[] = ['table'];
+    views: ('table' | 'venn')[] = ['table'];
+
+    /**
+     * 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;
+
+    /**
+     * 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 variants={this.variants} sequenceType={this.sequenceType} views={this.views} />;
+        return (
+            <MutationComparison
+                variants={this.variants}
+                sequenceType={this.sequenceType}
+                views={this.views}
+                size={this.size}
+                headline={this.headline}
+            />
+        );
     }
 }
 
@@ -29,3 +96,11 @@ declare global {
         'gs-mutation-comparison-component': MutationComparisonComponent;
     }
 }
+
+/* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars */
+type VariantsMatches = Expect<
+    Equals<typeof MutationComparisonComponent.prototype.variants, MutationComparisonVariant[]>
+>;
+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/display/mutations-component.stories.ts

@@ -4,15 +4,23 @@ import { html } from 'lit';
 
 import './mutations-component';
 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',
+    component: 'gs-mutations-component',
     argTypes: {
         variant: { control: 'object' },
         sequenceType: {
@@ -23,32 +31,45 @@ const meta: Meta<MutationsProps> = {
             options: ['table', 'grid', 'insertions'],
             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: {
+            tag: 'gs-mutations-component',
+            opensShadowDom: true,
+            expectsChildren: false,
+            codeExample,
+        },
+    }),
+    tags: ['autodocs'],
 };
 
 export default meta;
 
 const Template: StoryObj<MutationsProps> = {
     render: (args) => html`
-        <div class="w-11/12 h-11/12">
-            <gs-app lapis="${LAPIS_URL}">
-                <gs-mutations-component
-                    .variant=${args.variant}
-                    .sequenceType=${args.sequenceType}
-                    .views=${args.views}
-                ></gs-mutations-component>
-            </gs-app>
-        </div>
+        <gs-app lapis="${LAPIS_URL}">
+            <gs-mutations-component
+                .variant=${args.variant}
+                .sequenceType=${args.sequenceType}
+                .views=${args.views}
+                .size=${args.size}
+                .headline=${args.headline}
+            ></gs-mutations-component>
+        </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'],
-    },
     parameters: {
         fetchMock: {
             mocks: [
@@ -89,9 +110,9 @@ export const OnTableTab: StoryObj<MutationsProps> = {
     play: async ({ canvasElement }) => {
         const canvas = await withinShadowRoot(canvasElement, 'gs-mutations-component');
 
-        await waitFor(() => expect(canvas.getByLabelText('Table', { selector: 'input' })).toBeInTheDocument());
+        await waitFor(() => expect(canvas.getByRole('button', { name: 'Table' })).toBeInTheDocument());
 
-        await fireEvent.click(canvas.getByLabelText('Table', { selector: 'input' }));
+        await fireEvent.click(canvas.getByRole('button', { name: 'Table' }));
     },
 };
 
@@ -100,8 +121,8 @@ export const OnInsertionsTab: StoryObj<MutationsProps> = {
     play: async ({ canvasElement }) => {
         const canvas = await withinShadowRoot(canvasElement, 'gs-mutations-component');
 
-        await waitFor(() => expect(canvas.getByLabelText('Insertions', { selector: 'input' })).toBeInTheDocument());
+        await waitFor(() => expect(canvas.getByRole('button', { name: 'Insertions' })).toBeInTheDocument());
 
-        await fireEvent.click(canvas.getByLabelText('Insertions', { selector: 'input' }));
+        await fireEvent.click(canvas.getByRole('button', { name: 'Insertions' }));
     },
 };