@genspectrum/dashboard-components 1.6.0 → 1.8.0

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

@@ -11,6 +11,7 @@ import { referenceGenomeContext } from './reference-genome-context';
 import { withComponentDocs } from '../../.storybook/ComponentDocsBlock';
 import { LAPIS_URL, REFERENCE_GENOME_ENDPOINT } from '../constants';
 import { type MutationAnnotations, mutationAnnotationsContext } from './mutation-annotations-context';
+import { type MutationLinkTemplate, mutationLinkTemplateContext } from './mutation-link-template-context';
 import type { ReferenceGenome } from '../lapisApi/ReferenceGenome';
 import referenceGenome from '../lapisApi/__mockData__/referenceGenome.json';
 
@@ -35,11 +36,19 @@ const meta: Meta = {
 
 export default meta;
 
-type StoryProps = { lapis: string; mutationAnnotations: MutationAnnotations };
+type StoryProps = {
+    lapis: string;
+    mutationAnnotations: MutationAnnotations;
+    mutationLinkTemplate: MutationLinkTemplate;
+};
 
 const Template: StoryObj<StoryProps> = {
     render: (args) => {
-        return html` <gs-app lapis="${args.lapis}" .mutationAnnotations="${args.mutationAnnotations}">
+        return html` <gs-app
+            lapis="${args.lapis}"
+            .mutationAnnotations="${args.mutationAnnotations}"
+            .mutationLinkTemplate="${args.mutationLinkTemplate}"
+        >
             <gs-app-display></gs-app-display>
         </gs-app>`;
     },
@@ -56,6 +65,10 @@ const Template: StoryObj<StoryProps> = {
                 aminoAcidPositions: ['S:123'],
             },
         ],
+        mutationLinkTemplate: {
+            nucleotideMutation: 'http://foo.com/query?nucMut={{mutation}}',
+            aminoAcidMutation: 'http://foo.com/query?aaMut={{mutation}}',
+        },
     },
 };
 
@@ -128,6 +141,18 @@ export const FailsToFetchReferenceGenome: StoryObj<StoryProps> = {
     },
 };
 
+export const ProvidesMutationLinkTemplateToChildren: StoryObj<StoryProps> = {
+    ...Template,
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+
+        await waitFor(async () => {
+            await expect(canvas.getByText('http://foo.com/query?nucMut={{mutation}}', { exact: false })).toBeVisible();
+            await expect(canvas.getByText('http://foo.com/query?aaMut={{mutation}}', { exact: false })).toBeVisible();
+        });
+    },
+};
+
 @customElement('gs-app-display')
 // eslint-disable-next-line @typescript-eslint/no-unused-vars -- it is used in the story above
 class AppDisplay extends LitElement {
@@ -143,6 +168,9 @@ class AppDisplay extends LitElement {
     @consume({ context: mutationAnnotationsContext, subscribe: true })
     mutationAnnotations: MutationAnnotations = [];
 
+    @consume({ context: mutationLinkTemplateContext, subscribe: true })
+    mutationLinkTemplate: MutationLinkTemplate = {};
+
     override render() {
         return html`
             <h1 class="text-xl font-bold">Dummy component</h1>
@@ -156,6 +184,8 @@ class AppDisplay extends LitElement {
             <pre><code>${JSON.stringify(this.referenceGenome, null, 2)}</code></pre>
             <h2 class="text-lg font-bold">Mutation annotations</h2>
             <pre><code>${JSON.stringify(this.mutationAnnotations, null, 2)}</code></pre>
+            <h2 class="text-lg font-bold">Mutation link template</h2>
+            <pre><code>${JSON.stringify(this.mutationLinkTemplate, null, 2)}</code></pre>
         `;
     }
 

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

@@ -7,6 +7,7 @@ import z from 'zod';
 
 import { lapisContext } from './lapis-context';
 import { mutationAnnotationsContext } from './mutation-annotations-context';
+import { mutationLinkTemplateContext } from './mutation-link-template-context';
 import { referenceGenomeContext } from './reference-genome-context';
 import { type ReferenceGenome } from '../lapisApi/ReferenceGenome';
 import { fetchReferenceGenome } from '../lapisApi/lapisApi';
@@ -59,6 +60,22 @@ export class AppComponent extends LitElement {
         aminoAcidPositions?: string[];
     }[] = [];
 
+    /**
+     * Supply a link template for nucleotide and amino acid mutations.
+     * The template should include '{{mutation}}' where the mutation code will be inserted, for example:
+     *
+     *     https://my-site.org/query?nucleotideMutation={{mutation}}
+     */
+    @provide({ context: mutationLinkTemplateContext })
+    @property({ type: Object })
+    mutationLinkTemplate: {
+        nucleotideMutation?: string;
+        aminoAcidMutation?: string;
+    } = {
+        nucleotideMutation: undefined,
+        aminoAcidMutation: undefined,
+    };
+
     /**
      * @internal
      */

package/src/web-components/input/gs-mutation-filter.stories.ts

@@ -7,6 +7,7 @@ import { previewHandles } from '../../../.storybook/preview';
 import { LAPIS_URL, REFERENCE_GENOME_ENDPOINT } from '../../constants';
 import '../gs-app';
 import { type MutationFilterProps } from '../../preact/mutationFilter/mutation-filter';
+import { mutationType } from '../../types';
 import { gsEventNames } from '../../utils/gsEventNames';
 import { withinShadowRoot } from '../withinShadowRoot.story';
 import './gs-mutation-filter';
@@ -117,7 +118,7 @@ export const RestrictEnabledMutationTypes: StoryObj<MutationFilterProps> = {
     ...Template,
     args: {
         ...Template.args,
-        enabledMutationTypes: ['nucleotideMutations', 'aminoAcidMutations'],
+        enabledMutationTypes: [mutationType.nucleotideMutations, mutationType.aminoAcidMutations],
     },
     play: async ({ canvasElement }) => {
         const canvas = await withinShadowRoot(canvasElement, 'gs-mutation-filter');

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

@@ -2,12 +2,8 @@ import { customElement, property } from 'lit/decorators.js';
 import type { DetailedHTMLProps, HTMLAttributes } from 'react';
 
 import { ReferenceGenomesAwaiter } from '../../preact/components/ReferenceGenomesAwaiter';
-import {
-    MutationFilter,
-    type MutationType,
-    type MutationFilterProps,
-} from '../../preact/mutationFilter/mutation-filter';
-import type { MutationsFilter } from '../../types';
+import { MutationFilter, type MutationFilterProps } from '../../preact/mutationFilter/mutation-filter';
+import type { MutationType, MutationsFilter } from '../../types';
 import { type gsEventNames } from '../../utils/gsEventNames';
 import type { Equals, Expect } from '../../utils/typeAssertions';
 import { PreactLitAdapter } from '../PreactLitAdapter';

package/src/web-components/mutation-link-template-context.ts

@@ -0,0 +1,13 @@
+import { createContext } from '@lit/context';
+import z from 'zod';
+
+export const mutationLinkTemplateSchema = z.object({
+    nucleotideMutation: z.string().optional(),
+    aminoAcidMutation: z.string().optional(),
+});
+
+export type MutationLinkTemplate = z.infer<typeof mutationLinkTemplateSchema>;
+
+export const mutationLinkTemplateContext = createContext<MutationLinkTemplate>(
+    Symbol('mutation-link-template-context'),
+);

package/src/web-components/mutationLinks.mdx

@@ -0,0 +1,27 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title='Concepts/External Mutation Links' />
+
+# External Mutation Links
+
+When inspecting mutations, you might want to be able to quickly look up a mutation somewhere else.
+For this, it's possible to supply a _link template_ which will then lead to mutation labels being clickable using
+that link template.
+
+The mutation link template can be (optionally) supplied to `gs-app` as a JSON object:
+
+```html
+<gs-app
+    lapis="https://your.lapis.url"
+    mutationLinkTemplate='{
+        "nucleotideMutation": "https://cov-spectrum.org/explore/Switzerland/AllSamples/Past6M/variants?nucMutations={{mutation}}",
+        "aminoAcidMutation": "https://cov-spectrum.org/explore/Switzerland/AllSamples/Past6M/variants?aaMutations={{mutation}}",
+    }'
+>
+    {/* children... */}
+</gs-app>
+```
+
+For example (like in the code above) you can directly link to cov-spectrum.
+
+Your link needs to have the placeholder `{{mutation}}` in it, which will then be replaced with the mutation code.

package/src/web-components/visualization/gs-mutation-comparison.tsx

@@ -3,10 +3,12 @@ import { customElement, property } from 'lit/decorators.js';
 import type { DetailedHTMLProps, HTMLAttributes } from 'react';
 
 import { MutationAnnotationsContextProvider } from '../../preact/MutationAnnotationsContext';
+import { MutationLinkTemplateContextProvider } from '../../preact/MutationLinkTemplateContext';
 import { MutationComparison, type MutationComparisonProps } from '../../preact/mutationComparison/mutation-comparison';
 import { type Equals, type Expect } from '../../utils/typeAssertions';
 import { PreactLitAdapterWithGridJsStyles } from '../PreactLitAdapterWithGridJsStyles';
 import { type MutationAnnotations, mutationAnnotationsContext } from '../mutation-annotations-context';
+import { type MutationLinkTemplate, mutationLinkTemplateContext } from '../mutation-link-template-context';
 
 /**
  * ## Context
@@ -103,17 +105,25 @@ export class MutationComparisonComponent extends PreactLitAdapterWithGridJsStyle
     @consume({ context: mutationAnnotationsContext, subscribe: true })
     mutationAnnotations: MutationAnnotations = [];
 
+    /**
+     * @internal
+     */
+    @consume({ context: mutationLinkTemplateContext, subscribe: true })
+    mutationLinkTemplate: MutationLinkTemplate = {};
+
     override render() {
         return (
             <MutationAnnotationsContextProvider value={this.mutationAnnotations}>
-                <MutationComparison
-                    lapisFilters={this.lapisFilters}
-                    sequenceType={this.sequenceType}
-                    views={this.views}
-                    width={this.width}
-                    height={this.height}
-                    pageSize={this.pageSize}
-                />
+                <MutationLinkTemplateContextProvider value={this.mutationLinkTemplate}>
+                    <MutationComparison
+                        lapisFilters={this.lapisFilters}
+                        sequenceType={this.sequenceType}
+                        views={this.views}
+                        width={this.width}
+                        height={this.height}
+                        pageSize={this.pageSize}
+                    />
+                </MutationLinkTemplateContextProvider>
             </MutationAnnotationsContextProvider>
         );
     }

package/src/web-components/visualization/gs-mutations-over-time.stories.ts

@@ -89,9 +89,20 @@ const mutationAnnotations = [
     },
 ];
 
+const mutationLinkTemplate = {
+    nucleotideMutation:
+        'https://cov-spectrum.org/explore/Switzerland/AllSamples/Past6M/variants?nucMutations={{mutation}}',
+    aminoAcidMutation:
+        'https://cov-spectrum.org/explore/Switzerland/AllSamples/Past6M/variants?aaMutations={{mutation}}',
+};
+
 const Template: StoryObj<Required<MutationsOverTimeProps>> = {
     render: (args) => html`
-        <gs-app lapis="${LAPIS_URL}" .mutationAnnotations=${mutationAnnotations}>
+        <gs-app
+            lapis="${LAPIS_URL}"
+            .mutationAnnotations=${mutationAnnotations}
+            .mutationLinkTemplate=${mutationLinkTemplate}
+        >
             <gs-mutations-over-time
                 .lapisFilter=${args.lapisFilter}
                 .sequenceType=${args.sequenceType}

package/src/web-components/visualization/gs-mutations-over-time.tsx

@@ -3,9 +3,11 @@ import { customElement, property } from 'lit/decorators.js';
 import type { DetailedHTMLProps, HTMLAttributes } from 'react';
 
 import { MutationAnnotationsContextProvider } from '../../preact/MutationAnnotationsContext';
+import { MutationLinkTemplateContextProvider } from '../../preact/MutationLinkTemplateContext';
 import { MutationsOverTime } from '../../preact/mutationsOverTime/mutations-over-time';
 import { PreactLitAdapterWithGridJsStyles } from '../PreactLitAdapterWithGridJsStyles';
 import { type MutationAnnotations, mutationAnnotationsContext } from '../mutation-annotations-context';
+import { type MutationLinkTemplate, mutationLinkTemplateContext } from '../mutation-link-template-context';
 
 /**
  * ## Context
@@ -140,23 +142,31 @@ export class MutationsOverTimeComponent extends PreactLitAdapterWithGridJsStyles
     @consume({ context: mutationAnnotationsContext, subscribe: true })
     mutationAnnotations: MutationAnnotations = [];
 
+    /**
+     * @internal
+     */
+    @consume({ context: mutationLinkTemplateContext, subscribe: true })
+    mutationLinkTemplate: MutationLinkTemplate = {};
+
     override render() {
         return (
             <MutationAnnotationsContextProvider value={this.mutationAnnotations}>
-                <MutationsOverTime
-                    lapisFilter={this.lapisFilter}
-                    sequenceType={this.sequenceType}
-                    views={this.views}
-                    width={this.width}
-                    height={this.height}
-                    granularity={this.granularity}
-                    lapisDateField={this.lapisDateField}
-                    displayMutations={this.displayMutations}
-                    initialMeanProportionInterval={this.initialMeanProportionInterval}
-                    hideGaps={this.hideGaps}
-                    useNewEndpoint={this.useNewEndpoint}
-                    pageSizes={this.pageSizes}
-                />
+                <MutationLinkTemplateContextProvider value={this.mutationLinkTemplate}>
+                    <MutationsOverTime
+                        lapisFilter={this.lapisFilter}
+                        sequenceType={this.sequenceType}
+                        views={this.views}
+                        width={this.width}
+                        height={this.height}
+                        granularity={this.granularity}
+                        lapisDateField={this.lapisDateField}
+                        displayMutations={this.displayMutations}
+                        initialMeanProportionInterval={this.initialMeanProportionInterval}
+                        hideGaps={this.hideGaps}
+                        useNewEndpoint={this.useNewEndpoint}
+                        pageSizes={this.pageSizes}
+                    />
+                </MutationLinkTemplateContextProvider>
             </MutationAnnotationsContextProvider>
         );
     }

package/src/web-components/visualization/gs-mutations.tsx

@@ -3,10 +3,12 @@ import { customElement, property } from 'lit/decorators.js';
 import type { DetailedHTMLProps, HTMLAttributes } from 'react';
 
 import { MutationAnnotationsContextProvider } from '../../preact/MutationAnnotationsContext';
+import { MutationLinkTemplateContextProvider } from '../../preact/MutationLinkTemplateContext';
 import { Mutations, type MutationsProps } from '../../preact/mutations/mutations';
 import type { Equals, Expect } from '../../utils/typeAssertions';
 import { PreactLitAdapterWithGridJsStyles } from '../PreactLitAdapterWithGridJsStyles';
 import { type MutationAnnotations, mutationAnnotationsContext } from '../mutation-annotations-context';
+import { type MutationLinkTemplate, mutationLinkTemplateContext } from '../mutation-link-template-context';
 
 /**
  * ## Context
@@ -134,18 +136,26 @@ export class MutationsComponent extends PreactLitAdapterWithGridJsStyles {
     @consume({ context: mutationAnnotationsContext, subscribe: true })
     mutationAnnotations: MutationAnnotations = [];
 
+    /**
+     * @internal
+     */
+    @consume({ context: mutationLinkTemplateContext, subscribe: true })
+    mutationLinkTemplate: MutationLinkTemplate = {};
+
     override render() {
         return (
             <MutationAnnotationsContextProvider value={this.mutationAnnotations}>
-                <Mutations
-                    lapisFilter={this.lapisFilter}
-                    sequenceType={this.sequenceType}
-                    views={this.views}
-                    width={this.width}
-                    height={this.height}
-                    pageSize={this.pageSize}
-                    baselineLapisFilter={this.baselineLapisFilter}
-                />
+                <MutationLinkTemplateContextProvider value={this.mutationLinkTemplate}>
+                    <Mutations
+                        lapisFilter={this.lapisFilter}
+                        sequenceType={this.sequenceType}
+                        views={this.views}
+                        width={this.width}
+                        height={this.height}
+                        pageSize={this.pageSize}
+                        baselineLapisFilter={this.baselineLapisFilter}
+                    />
+                </MutationLinkTemplateContextProvider>
             </MutationAnnotationsContextProvider>
         );
     }

package/src/web-components/wastewaterVisualization/gs-wastewater-mutations-over-time.tsx

@@ -3,9 +3,11 @@ import { customElement, property } from 'lit/decorators.js';
 import { type DetailedHTMLProps, type HTMLAttributes } from 'react';
 
 import { MutationAnnotationsContextProvider } from '../../preact/MutationAnnotationsContext';
+import { MutationLinkTemplateContextProvider } from '../../preact/MutationLinkTemplateContext';
 import { WastewaterMutationsOverTime } from '../../preact/wastewater/mutationsOverTime/wastewater-mutations-over-time';
 import { PreactLitAdapterWithGridJsStyles } from '../PreactLitAdapterWithGridJsStyles';
 import { type MutationAnnotations, mutationAnnotationsContext } from '../mutation-annotations-context';
+import { type MutationLinkTemplate, mutationLinkTemplateContext } from '../mutation-link-template-context';
 
 /**
  * ## Context
@@ -79,16 +81,24 @@ export class WastewaterMutationsOverTimeComponent extends PreactLitAdapterWithGr
     @consume({ context: mutationAnnotationsContext, subscribe: true })
     mutationAnnotations: MutationAnnotations = [];
 
+    /**
+     * @internal
+     */
+    @consume({ context: mutationLinkTemplateContext, subscribe: true })
+    mutationLinkTemplate: MutationLinkTemplate = {};
+
     override render() {
         return (
             <MutationAnnotationsContextProvider value={this.mutationAnnotations}>
-                <WastewaterMutationsOverTime
-                    lapisFilter={this.lapisFilter}
-                    sequenceType={this.sequenceType}
-                    width={this.width}
-                    height={this.height}
-                    pageSizes={this.pageSizes}
-                />
+                <MutationLinkTemplateContextProvider value={this.mutationLinkTemplate}>
+                    <WastewaterMutationsOverTime
+                        lapisFilter={this.lapisFilter}
+                        sequenceType={this.sequenceType}
+                        width={this.width}
+                        height={this.height}
+                        pageSizes={this.pageSizes}
+                    />
+                </MutationLinkTemplateContextProvider>
             </MutationAnnotationsContextProvider>
         );
     }