@genspectrum/dashboard-components 1.7.0 → 1.8.1

package/src/utils/mutations.ts

@@ -17,15 +17,19 @@ export interface MutationClass extends Mutation {
 const nucleotideChars = 'ACGTRYKMSWBDHVN';
 const aminoAcidChars = 'ACDEFGHIKLMNPQRSTVWY';
 
-function segmentPart(type: 'nucleotide' | 'aminoAcid') {
-    return type === 'aminoAcid' ? `(?<segment>[A-Z0-9_-]+):` : `((?<segment>[A-Z0-9_-]+)(?=:):)?`;
+function segmentPart(isOptional: boolean) {
+    const segmentPart = `(?<segment>[A-Z0-9_-]+):`;
+    if (isOptional) {
+        return `(${segmentPart})?`;
+    }
+    return segmentPart;
 }
 
-function buildSubstitutionRegex(type: 'nucleotide' | 'aminoAcid') {
+function buildSubstitutionRegex(type: 'nucleotide' | 'aminoAcid', segmentPartIsOptional: boolean) {
     const chars = type === 'nucleotide' ? nucleotideChars : aminoAcidChars;
 
     return new RegExp(
-        `^${segmentPart(type)}` +
+        `^${segmentPart(segmentPartIsOptional)}` +
             `(?<valueAtReference>[${chars}*])?` +
             `(?<position>\\d+)` +
             `(?<substitutionValue>[${chars}.*])?$`,
@@ -33,8 +37,9 @@ function buildSubstitutionRegex(type: 'nucleotide' | 'aminoAcid') {
     );
 }
 
-const nucleotideSubstitutionRegex = buildSubstitutionRegex('nucleotide');
-const aminoAcidSubstitutionRegex = buildSubstitutionRegex('aminoAcid');
+const nucleotideSubstitutionRegex = buildSubstitutionRegex('nucleotide', true);
+const aminoAcidSubstitutionRegex = buildSubstitutionRegex('aminoAcid', false);
+const aminoAcidSubstitutionWithoutSegmentRegex = buildSubstitutionRegex('aminoAcid', true);
 
 export interface Substitution extends Mutation {
     type: 'substitution';
@@ -74,10 +79,13 @@ export class SubstitutionClass implements MutationClass, Substitution {
         return this.code;
     }
 
-    static parse(mutationStr: string): SubstitutionClass | null {
+    static parse(mutationStr: string, segmentIsOptional: boolean = false): SubstitutionClass | null {
         const matchNucleotide = nucleotideSubstitutionRegex.exec(mutationStr);
         const matchAminoAcid = aminoAcidSubstitutionRegex.exec(mutationStr);
-        const match = matchNucleotide ?? matchAminoAcid;
+        const matchAminAcidWithoutSegment = segmentIsOptional
+            ? aminoAcidSubstitutionWithoutSegmentRegex.exec(mutationStr)
+            : undefined;
+        const match = matchNucleotide ?? matchAminoAcid ?? matchAminAcidWithoutSegment;
         if (match?.groups === undefined) {
             return null;
         }
@@ -94,7 +102,7 @@ function buildDeletionRegex(type: 'nucleotide' | 'aminoAcid') {
     const chars = type === 'nucleotide' ? nucleotideChars : aminoAcidChars;
 
     return new RegExp(
-        `^${segmentPart(type)}` + `(?<valueAtReference>[${chars}*])?` + `(?<position>\\d+)` + `(-)$`,
+        `^${segmentPart(type === 'nucleotide')}` + `(?<valueAtReference>[${chars}*])?` + `(?<position>\\d+)` + `(-)$`,
         'i',
     );
 }
@@ -158,7 +166,7 @@ function buildInsertionRegex(type: 'nucleotide' | 'aminoAcid') {
     const wildcardToken = `(?:\\.\\*)`;
 
     return new RegExp(
-        `^ins_${segmentPart(type)}(?<position>\\d+):(?<insertedSymbols>(?:[${chars}?*]|${wildcardToken})+)$`,
+        `^ins_${segmentPart(type === 'nucleotide')}(?<position>\\d+):(?<insertedSymbols>(?:[${chars}?*]|${wildcardToken})+)$`,
         'i',
     );
 }

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

@@ -2,9 +2,16 @@ import { describe, expectTypeOf, test } from 'vitest';
 
 import { AppComponent } from './gs-app';
 import { type MutationAnnotations } from './mutation-annotations-context';
+import { type MutationLinkTemplate } from './mutation-link-template-context';
 
 describe('gs-app types', () => {
     test('mutationAnnotations type should match', () => {
         expectTypeOf(AppComponent.prototype).toHaveProperty('mutationAnnotations').toEqualTypeOf<MutationAnnotations>();
     });
+
+    test('mutationLinkTemplate type should match', () => {
+        expectTypeOf(AppComponent.prototype)
+            .toHaveProperty('mutationLinkTemplate')
+            .toEqualTypeOf<MutationLinkTemplate>();
+    });
 });

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/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>
         );
     }