@genspectrum/dashboard-components 0.1.3 → 0.1.4

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,9 @@ const meta: Meta<AggregateProps> = {
             options: ['table'],
             control: { type: 'check' },
         },
+        size: [{ control: 'object' }],
     },
-    parameters: {
+    parameters: withComponentDocs({
         fetchMock: {
             mocks: [
                 {
@@ -36,22 +39,28 @@ 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}
+            ></gs-aggregate-component>
+        </gs-app>
     `,
     args: {
         fields: ['division', 'host'],
@@ -59,5 +68,6 @@ export const Table: StoryObj<AggregateProps> = {
         filter: {
             country: 'USA',
         },
+        size: { width: '100%', height: '700px' },
     },
 };

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,19 @@ 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;
+
     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} />;
     }
 }
 

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' }));
     },
 };

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

@@ -15,8 +15,21 @@ export class MutationsComponent extends PreactLitAdapterWithGridJsStyles {
     @property({ type: Array })
     views: View[] = ['table', 'grid'];
 
+    /**
+     * 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 <Mutations variant={this.variant} sequenceType={this.sequenceType} views={this.views} />;
+        return (
+            <Mutations variant={this.variant} sequenceType={this.sequenceType} views={this.views} size={this.size} />
+        );
     }
 }
 

package/src/web-components/display/prevalence-over-time-component.stories.ts

@@ -32,6 +32,7 @@ const meta: Meta<PrevalenceOverTimeProps> = {
             options: ['wilson'],
             control: { type: 'check' },
         },
+        size: [{ control: 'object' }],
     },
 };
 
@@ -39,18 +40,17 @@ export default meta;
 
 const Template: StoryObj<PrevalenceOverTimeProps> = {
     render: (args) => html`
-        <div class="w-11/12 h-11/12">
-            <gs-app lapis="${LAPIS_URL}">
-                <gs-prevalence-over-time
-                    .numerator=${args.numerator}
-                    .denominator=${args.denominator}
-                    .granularity=${args.granularity}
-                    .smoothingWindow=${args.smoothingWindow}
-                    .views=${args.views}
-                    .confidenceIntervalMethods=${args.confidenceIntervalMethods}
-                ></gs-prevalence-over-time>
-            </gs-app>
-        </div>
+        <gs-app lapis="${LAPIS_URL}">
+            <gs-prevalence-over-time
+                .numerator=${args.numerator}
+                .denominator=${args.denominator}
+                .granularity=${args.granularity}
+                .smoothingWindow=${args.smoothingWindow}
+                .views=${args.views}
+                .confidenceIntervalMethods=${args.confidenceIntervalMethods}
+                .size=${args.size}
+            ></gs-prevalence-over-time>
+        </gs-app>
     `,
 };
 
@@ -66,6 +66,7 @@ export const TwoVariants: StoryObj<PrevalenceOverTimeProps> = {
         smoothingWindow: 0,
         views: ['bar', 'line', 'bubble', 'table'],
         confidenceIntervalMethods: ['wilson'],
+        size: { width: '100%', height: '700px' },
     },
     parameters: {
         fetchMock: {
@@ -131,6 +132,7 @@ export const OneVariant: StoryObj<PrevalenceOverTimeProps> = {
         smoothingWindow: 7,
         views: ['bar', 'line', 'bubble', 'table'],
         confidenceIntervalMethods: ['wilson'],
+        size: { width: '100%', height: '700px' },
     },
     parameters: {
         fetchMock: {
@@ -176,9 +178,9 @@ export const OneVariantOnLineTab: StoryObj<PrevalenceOverTimeProps> = {
     play: async ({ canvasElement }) => {
         const canvas = await withinShadowRoot(canvasElement, 'gs-prevalence-over-time');
 
-        await waitFor(() => expect(canvas.getByLabelText('Line', { selector: 'input' })).toBeInTheDocument());
+        await waitFor(() => expect(canvas.getByRole('button', { name: 'Line' })).toBeInTheDocument());
 
-        await fireEvent.click(canvas.getByLabelText('Line', { selector: 'input' }));
+        await fireEvent.click(canvas.getByRole('button', { name: 'Line' }));
     },
 };
 
@@ -187,9 +189,9 @@ export const OneVariantOnBubbleTab: StoryObj<PrevalenceOverTimeProps> = {
     play: async ({ canvasElement }) => {
         const canvas = await withinShadowRoot(canvasElement, 'gs-prevalence-over-time');
 
-        await waitFor(() => expect(canvas.getByLabelText('Bubble', { selector: 'input' })).toBeInTheDocument());
+        await waitFor(() => expect(canvas.getByRole('button', { name: 'Bubble' })).toBeInTheDocument());
 
-        await fireEvent.click(canvas.getByLabelText('Bubble', { selector: 'input' }));
+        await fireEvent.click(canvas.getByRole('button', { name: 'Bubble' }));
     },
 };
 
@@ -198,8 +200,8 @@ export const OneVariantOnTableTab: StoryObj<PrevalenceOverTimeProps> = {
     play: async ({ canvasElement }) => {
         const canvas = await withinShadowRoot(canvasElement, 'gs-prevalence-over-time');
 
-        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' }));
     },
 };

package/src/web-components/display/prevalence-over-time-component.tsx

@@ -25,6 +25,17 @@ export class PrevalenceOverTimeComponent extends PreactLitAdapterWithGridJsStyle
     @property({ type: Array })
     confidenceIntervalMethods: ConfidenceIntervalMethod[] = ['wilson'];
 
+    /**
+     * 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 (
             <PrevalenceOverTime
@@ -34,6 +45,7 @@ export class PrevalenceOverTimeComponent extends PreactLitAdapterWithGridJsStyle
                 smoothingWindow={this.smoothingWindow}
                 views={this.views}
                 confidenceIntervalMethods={this.confidenceIntervalMethods}
+                size={this.size}
             />
         );
     }

package/src/web-components/display/relative-growth-advantage-component.stories.ts

@@ -19,6 +19,7 @@ const meta: Meta<RelativeGrowthAdvantageProps> = {
             options: ['line'],
             control: { type: 'check' },
         },
+        size: [{ control: 'object' }],
     },
 };
 
@@ -26,16 +27,15 @@ export default meta;
 
 const Template: StoryObj<RelativeGrowthAdvantageProps> = {
     render: (args) => html`
-        <div class="w-11/12 h-11/12">
-            <gs-app lapis="${LAPIS_URL}">
-                <gs-relative-growth-advantage
-                    .numerator=${args.numerator}
-                    .denominator=${args.denominator}
-                    .generationTime=${args.generationTime}
-                    .views=${args.views}
-                ></gs-relative-growth-advantage>
-            </gs-app>
-        </div>
+        <gs-app lapis="${LAPIS_URL}">
+            <gs-relative-growth-advantage
+                .numerator=${args.numerator}
+                .denominator=${args.denominator}
+                .generationTime=${args.generationTime}
+                .views=${args.views}
+                .size=${args.size}
+            ></gs-relative-growth-advantage>
+        </gs-app>
     `,
 };
 
@@ -46,6 +46,7 @@ export const Default: StoryObj<RelativeGrowthAdvantageProps> = {
         denominator: { country: 'Switzerland', dateFrom: '2020-12-01', dateTo: '2021-03-01' },
         generationTime: 7,
         views: ['line'],
+        size: { width: '100%', height: '700px' },
     },
     parameters: {
         fetchMock: {

package/src/web-components/display/relative-growth-advantage-component.tsx

@@ -18,6 +18,17 @@ export class RelativeGrowthAdvantageComponent extends PreactLitAdapter {
     @property({ type: Array })
     views: View[] = ['line'];
 
+    /**
+     * 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 (
             <RelativeGrowthAdvantage
@@ -25,6 +36,7 @@ export class RelativeGrowthAdvantageComponent extends PreactLitAdapter {
                 denominator={this.denominator}
                 generationTime={this.generationTime}
                 views={this.views}
+                size={this.size}
             />
         );
     }