@genspectrum/dashboard-components 0.1.2 → 0.1.4

package/src/query/queryAggregateData.ts

@@ -0,0 +1,25 @@
+import { FetchAggregatedOperator } from '../operator/FetchAggregatedOperator';
+import { type LapisFilter } from '../types';
+
+export type AggregateData = (Record<string, string | null | number | boolean> & {
+    count: number;
+    proportion: number;
+})[];
+
+export async function queryAggregateData(variant: LapisFilter, fields: string[], lapis: string, signal?: AbortSignal) {
+    const fetchData = new FetchAggregatedOperator<Record<string, string | null | number>>(variant, fields);
+    const data = (await fetchData.evaluate(lapis, signal)).content;
+
+    const total = data.reduce((acc, row) => acc + row.count, 0);
+
+    return data.map(
+        (row) =>
+            ({
+                ...row,
+                proportion: row.count / total,
+            }) as Record<string, string | null | number | boolean> & {
+                count: number;
+                proportion: number;
+            },
+    );
+}

package/src/utils/typeAssertions.spec.ts

@@ -0,0 +1,31 @@
+import { describe, it } from 'vitest';
+
+import { type Equals, type Expect } from './typeAssertions';
+
+/* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars */
+describe('Expect', () => {
+    it('should only accept true', () => {
+        type ShouldBeTrue = Expect<true>;
+        // @ts-expect-error Expect should only accept true
+        type ShouldFail = Expect<false>;
+    });
+});
+
+describe('Equals', () => {
+    it('should accept equal types', () => {
+        type Equals1 = Expect<Equals<1, 1>>;
+        type Equals1Or2 = Expect<Equals<1 | 2, 1 | 2>>;
+        type EqualsWithObject = Expect<Equals<{ key: string }, { key: string }>>;
+    });
+
+    it('should reject unequal types', () => {
+        // @ts-expect-error 1 is not 2
+        type Equals1Vs2 = Expect<Equals<1, 2>>;
+        // @ts-expect-error disjoint union types
+        type EqualsDisjointUnion = Expect<Equals<1 | 2, 1 | 999>>;
+        // @ts-expect-error object with different keys
+        type EqualsObjectWithDifferentKey = Expect<Equals<{ key: string }, { otherKey: string }>>;
+        // @ts-expect-error object with different value types
+        type EqualsObjectWithDifferentValue = Expect<Equals<{ key: string }, { key: number }>>;
+    });
+});

package/src/utils/typeAssertions.ts

@@ -0,0 +1,16 @@
+/**
+ * Those are helpers to make sure that types are equal.
+ *
+ * #### Why do we need this?
+ *
+ * The custom element manifest does not fully resolve the types of properties,
+ * so Storybook will only show non-resolved types (such as `View[]`).
+ * To give users full type information, we have to inline the types in the web component definitions.
+ * These assertions help us to make sure that the inlined type is equal to the type
+ * that is defined in the Preact components.
+ */
+
+export type Expect<T extends true> = T;
+export type IsAssignable<X, Y> = X extends Y ? true : false;
+export type And<X, Y> = X extends true ? (Y extends true ? true : false) : false;
+export type Equals<X, Y> = And<IsAssignable<X, Y>, IsAssignable<Y, X>>;

package/src/web-components/PreactLitAdapter.tsx

@@ -46,7 +46,6 @@ export abstract class PreactLitAdapter extends ReactiveElement {
     };
 
     override update(changedProperties: PropertyValues) {
-        console.log('this.lapis', this.lapis);
         const vdom = (
             <LapisUrlContext.Provider value={this.lapis}>
                 <ReferenceGenomeContext.Provider value={this.referenceGenome}>

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

@@ -0,0 +1,73 @@
+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';
+
+const meta: Meta<AggregateProps> = {
+    title: 'Visualization/Aggregate',
+    component: 'gs-aggregate-component',
+    argTypes: {
+        fields: [{ control: 'object' }],
+        views: {
+            options: ['table'],
+            control: { type: 'check' },
+        },
+        size: [{ control: 'object' }],
+    },
+    parameters: withComponentDocs({
+        fetchMock: {
+            mocks: [
+                {
+                    matcher: {
+                        name: 'aggregatedData',
+                        url: AGGREGATED_ENDPOINT,
+                        body: {
+                            fields: ['division', 'host'],
+                            country: 'USA',
+                        },
+                    },
+                    response: {
+                        status: 200,
+                        body: aggregatedData,
+                    },
+                },
+            ],
+        },
+        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`
+        <gs-app lapis="${LAPIS_URL}">
+            <gs-aggregate-component
+                .fields=${args.fields}
+                .filter=${args.filter}
+                .views=${args.views}
+                .size=${args.size}
+            ></gs-aggregate-component>
+        </gs-app>
+    `,
+    args: {
+        fields: ['division', 'host'],
+        views: ['table'],
+        filter: {
+            country: 'USA',
+        },
+        size: { width: '100%', height: '700px' },
+    },
+};

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

@@ -0,0 +1,58 @@
+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, 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.
+ */
+@customElement('gs-aggregate-component')
+export class AggregateComponent extends PreactLitAdapterWithGridJsStyles {
+    /**
+     * The fields to aggregate by.
+     */
+    @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).
+     */
+    @property({ type: Array })
+    views: View[] = ['table'];
+
+    /**
+     * The filter to apply to the data.
+     */
+    @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;
+
+    override render() {
+        return <Aggregate fields={this.fields} views={this.views} filter={this.filter} size={this.size} />;
+    }
+}
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'gs-aggregate-component': AggregateComponent;
+    }
+}

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

@@ -2,3 +2,4 @@ export { MutationComparisonComponent } from './mutation-comparison-component';
 export { MutationsComponent } from './mutations-component';
 export { PrevalenceOverTimeComponent } from './prevalence-over-time-component';
 export { RelativeGrowthAdvantageComponent } from './relative-growth-advantage-component';
+export { AggregateComponent } from './aggregate-component';

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,31 @@ const meta: Meta<MutationComparisonProps> = {
             options: ['table', 'venn'],
             control: { type: 'check' },
         },
+        size: { control: 'object' },
     },
+    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}
+            ></gs-mutation-comparison-component>
+        </gs-app>
     `,
 };
 
@@ -65,6 +82,7 @@ export const Default: StoryObj<MutationComparisonProps> = {
         ],
         sequenceType: 'nucleotide',
         views: ['table', 'venn'],
+        size: { width: '100%', height: '700px' },
     },
     parameters: {
         fetchMock: {
@@ -124,9 +142,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,81 @@ 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;
 
     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}
+            />
+        );
     }
 }
 
@@ -29,3 +89,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

@@ -23,6 +23,7 @@ const meta: Meta<MutationsProps> = {
             options: ['table', 'grid', 'insertions'],
             control: { type: 'check' },
         },
+        size: { control: 'object' },
     },
 };
 
@@ -30,15 +31,14 @@ 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}
+            ></gs-mutations-component>
+        </gs-app>
     `,
 };
 
@@ -48,6 +48,7 @@ export const Default: StoryObj<MutationsProps> = {
         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: {
@@ -89,9 +90,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 +101,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' }));
     },
 };