@genspectrum/dashboard-components 0.16.2 → 0.16.3

package/src/preact/components/modal.stories.tsx

@@ -1,35 +1,23 @@
 import { type Meta, type StoryObj } from '@storybook/preact';
 import { expect, waitFor, within } from '@storybook/test';
-import { type FunctionComponent } from 'preact';
 
-import { Modal, type ModalProps, useModalRef } from './modal';
+import { Modal, ModalDialog, type ModalProps } from './modal';
 
 const meta: Meta<ModalProps> = {
     title: 'Component/Modal',
-    component: Modal,
+    component: ModalDialog,
     parameters: { fetchMock: {} },
 };
 
 export default meta;
 
-const WrapperWithButtonThatOpensTheModal: FunctionComponent = () => {
-    const modalRef = useModalRef();
-
-    return (
-        <div>
-            <button className='btn' onClick={() => modalRef.current?.showModal()}>
-                Open modal
-            </button>
-            <Modal modalRef={modalRef}>
-                <h1>Modal content</h1>
-            </Modal>
-        </div>
-    );
-};
-
 export const ModalStory: StoryObj<ModalProps> = {
     render: () => {
-        return <WrapperWithButtonThatOpensTheModal />;
+        return (
+            <Modal buttonClassName='btn' modalContent={<h1>Modal content</h1>}>
+                Open modal
+            </Modal>
+        );
     },
     play: async ({ canvasElement, step }) => {
         const canvas = within(canvasElement);

package/src/preact/components/modal.tsx

@@ -1,15 +1,46 @@
-import { type FunctionComponent, type Ref } from 'preact';
+import { type ComponentChildren, type FunctionComponent, type Ref, type RefObject } from 'preact';
 import { useRef } from 'preact/hooks';
 
-export type ModalProps = {
-    modalRef: Ref<HTMLDialogElement>;
+export type ModalButtonProps = {
+    buttonClassName?: string;
+    modalContent: ComponentChildren;
+};
+
+export const Modal: FunctionComponent<ModalButtonProps> = (props) => {
+    const modalRef = useModalRef();
+
+    return <ButtonWithModalDialog {...props} modalRef={modalRef} />;
+};
+
+type ButtonWithModalDialogProps = ModalButtonProps & {
+    modalRef: RefObject<HTMLDialogElement>;
+};
+
+export const ButtonWithModalDialog: FunctionComponent<ButtonWithModalDialogProps> = ({
+    children,
+    buttonClassName,
+    modalContent,
+    modalRef,
+}) => {
+    return (
+        <>
+            <button type='button' className={buttonClassName} onClick={() => modalRef.current?.showModal()}>
+                {children}
+            </button>
+            <ModalDialog modalRef={modalRef}>{modalContent}</ModalDialog>
+        </>
+    );
 };
 
 export function useModalRef() {
     return useRef<HTMLDialogElement>(null);
 }
 
-export const Modal: FunctionComponent<ModalProps> = ({ children, modalRef }) => {
+export type ModalProps = {
+    modalRef: Ref<HTMLDialogElement>;
+};
+
+export const ModalDialog: FunctionComponent<ModalProps> = ({ children, modalRef }) => {
     return (
         <dialog ref={modalRef} className={'modal modal-bottom sm:modal-middle'}>
             <div className='modal-box sm:max-w-5xl'>

package/src/preact/mutations/mutations-table.tsx

@@ -2,8 +2,10 @@ import { type FunctionComponent } from 'preact';
 import { useMemo } from 'preact/hooks';
 
 import { getMutationsTableData } from './getMutationsTableData';
-import { type SubstitutionOrDeletionEntry } from '../../types';
+import { type SequenceType, type SubstitutionOrDeletionEntry } from '../../types';
 import { type DeletionClass, type SubstitutionClass } from '../../utils/mutations';
+import { useMutationAnnotationsProvider } from '../MutationAnnotationsContext';
+import { GridJsAnnotatedMutation } from '../components/annotated-mutation';
 import type { ProportionInterval } from '../components/proportion-selector';
 import { Table } from '../components/table';
 import { sortSubstitutionsAndDeletions } from '../shared/sort/sortSubstitutionsAndDeletions';
@@ -15,6 +17,7 @@ export interface MutationsTableProps {
     overallVariantCount: number;
     proportionInterval: ProportionInterval;
     pageSize: boolean | number;
+    sequenceType: SequenceType;
 }
 
 const MutationsTable: FunctionComponent<MutationsTableProps> = ({
@@ -23,7 +26,10 @@ const MutationsTable: FunctionComponent<MutationsTableProps> = ({
     overallVariantCount,
     proportionInterval,
     pageSize,
+    sequenceType,
 }) => {
+    const annotationsProvider = useMutationAnnotationsProvider();
+
     const headers = [
         {
             name: 'Mutation',
@@ -32,7 +38,13 @@ const MutationsTable: FunctionComponent<MutationsTableProps> = ({
                     return sortSubstitutionsAndDeletions(a, b);
                 },
             },
-            formatter: (cell: SubstitutionClass | DeletionClass) => cell.toString(),
+            formatter: (cell: SubstitutionClass | DeletionClass) => (
+                <GridJsAnnotatedMutation
+                    mutation={cell}
+                    sequenceType={sequenceType}
+                    annotationsProvider={annotationsProvider}
+                />
+            ),
         },
         {
             name: 'Type',

package/src/preact/mutations/mutations.stories.tsx

@@ -1,5 +1,5 @@
 import { type Meta, type StoryObj } from '@storybook/preact';
-import { expect, waitFor, within } from '@storybook/test';
+import { expect, userEvent, waitFor, within } from '@storybook/test';
 
 import nucleotideInsertions from './__mockData__/nucleotideInsertions.json';
 import nucleotideMutations from './__mockData__/nucleotideMutations.json';
@@ -14,6 +14,7 @@ import referenceGenome from '../../lapisApi/__mockData__/referenceGenome.json';
 import baselineNucleotideMutations from '../../preact/mutations/__mockData__/baselineNucleotideMutations.json';
 import overallVariantCount from '../../preact/mutations/__mockData__/overallVariantCount.json';
 import { LapisUrlContextProvider } from '../LapisUrlContext';
+import { MutationAnnotationsContextProvider } from '../MutationAnnotationsContext';
 import { ReferenceGenomeContext } from '../ReferenceGenomeContext';
 
 const meta: Meta<MutationsProps> = {
@@ -37,11 +38,30 @@ const meta: Meta<MutationsProps> = {
 
 export default meta;
 
+const mutationAnnotations = [
+    {
+        name: 'I am a mutation annotation!',
+        description: 'This describes what is special about these mutations.',
+        symbol: '#',
+        nucleotideMutations: ['C241T', 'C3037T'],
+        aminoAcidMutations: ['N:G204R', 'N:S235F'],
+    },
+    {
+        name: 'I am another mutation annotation!',
+        description: 'This describes what is special about these other mutations.',
+        symbol: '+',
+        nucleotideMutations: ['C3037T', 'C11750T'],
+        aminoAcidMutations: ['ORF1a:S2255F'],
+    },
+];
+
 const Template = {
     render: (args: MutationsProps) => (
         <LapisUrlContextProvider value={LAPIS_URL}>
             <ReferenceGenomeContext.Provider value={referenceGenome}>
-                <Mutations {...args} />
+                <MutationAnnotationsContextProvider value={mutationAnnotations}>
+                    <Mutations {...args} />
+                </MutationAnnotationsContextProvider>
             </ReferenceGenomeContext.Provider>
         </LapisUrlContextProvider>
     ),
@@ -137,3 +157,21 @@ export const GridTab: StoryObj<MutationsProps> = {
         });
     },
 };
+
+export const TableTab: StoryObj<MutationsProps> = {
+    ...Default,
+    args: {
+        ...Default.args,
+        views: ['table'],
+    },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+
+        await waitFor(async () => {
+            const annotatedMutation = canvas.getByText('C241T');
+            await expect(annotatedMutation).toBeVisible();
+            await userEvent.click(annotatedMutation);
+        });
+        await waitFor(() => expect(canvas.getByText('Annotations for C241T')).toBeVisible());
+    },
+};

package/src/preact/mutations/mutations.tsx

@@ -109,6 +109,7 @@ const MutationsTabs: FunctionComponent<MutationTabsProps> = ({ mutationsData, or
                             overallVariantCount={mutationsData.overallVariantCount}
                             proportionInterval={proportionInterval}
                             pageSize={originalComponentProps.pageSize}
+                            sequenceType={originalComponentProps.sequenceType}
                         />
                     ),
                 };

package/src/preact/mutationsOverTime/mutations-over-time-grid.tsx

@@ -3,8 +3,10 @@ import { useRef } from 'preact/hooks';
 
 import { type MutationOverTimeDataMap } from './MutationOverTimeData';
 import { type MutationOverTimeMutationValue } from '../../query/queryMutationsOverTime';
+import { type SequenceType } from '../../types';
 import { type Deletion, type Substitution } from '../../utils/mutations';
 import { type Temporal, type TemporalClass, toTemporalClass, YearMonthDayClass } from '../../utils/temporalClass';
+import { AnnotatedMutation } from '../components/annotated-mutation';
 import { type ColorScale, getColorWithingScale, getTextColorForScale } from '../components/color-scale-selector';
 import Tooltip, { type TooltipPosition } from '../components/tooltip';
 import { formatProportion } from '../shared/table/formatProportion';
@@ -13,6 +15,7 @@ export interface MutationsOverTimeGridProps {
     data: MutationOverTimeDataMap;
     colorScale: ColorScale;
     maxNumberOfGridRows?: number;
+    sequenceType: SequenceType;
 }
 
 const MAX_NUMBER_OF_GRID_ROWS = 100;
@@ -22,6 +25,7 @@ const MutationsOverTimeGrid: FunctionComponent<MutationsOverTimeGridProps> = ({
     data,
     colorScale,
     maxNumberOfGridRows,
+    sequenceType,
 }) => {
     const currentMaxNumberOfGridRows = maxNumberOfGridRows ?? MAX_NUMBER_OF_GRID_ROWS;
     const allMutations = data.getFirstAxisKeys();
@@ -66,8 +70,9 @@ const MutationsOverTimeGrid: FunctionComponent<MutationsOverTimeGridProps> = ({
                                 <div
                                     key={`mutation-${mutation.code}`}
                                     style={{ gridRowStart: rowIndex + 2, gridColumnStart: 1 }}
+                                    className='flex items-center justify-center'
                                 >
-                                    <MutationCell mutation={mutation} />
+                                    <AnnotatedMutation mutation={mutation} sequenceType={sequenceType} />
                                 </div>
                                 {dates.map((date, columnIndex) => {
                                     const value = data.get(mutation, date) ?? null;
@@ -141,9 +146,12 @@ const ProportionCell: FunctionComponent<{
                 <>
                     <p>Proportion: {formatProportion(value.proportion)}</p>
                     {value.count !== null && value.totalCount !== null && (
-                        <p>
-                            Count: {value.count} / {value.totalCount} total
-                        </p>
+                        <>
+                            <p>
+                                {value.count} / {totalCountWithCoverage(value.count, value.proportion)} with coverage
+                            </p>
+                            <p>{value.totalCount} in timeframe</p>
+                        </>
                     )}
                 </>
             )}
@@ -169,6 +177,13 @@ const ProportionCell: FunctionComponent<{
     );
 };
 
+function totalCountWithCoverage(count: number, proportion: number) {
+    if (count === 0) {
+        return 0;
+    }
+    return Math.round(count / proportion);
+}
+
 const timeIntervalDisplay = (date: TemporalClass) => {
     if (date instanceof YearMonthDayClass) {
         return date.toString();
@@ -177,8 +192,4 @@ const timeIntervalDisplay = (date: TemporalClass) => {
     return `${date.firstDay.toString()} - ${date.lastDay.toString()}`;
 };
 
-const MutationCell: FunctionComponent<{ mutation: Substitution | Deletion }> = ({ mutation }) => {
-    return <div>{mutation.code}</div>;
-};
-
 export default MutationsOverTimeGrid;

package/src/preact/mutationsOverTime/mutations-over-time.stories.tsx

@@ -5,6 +5,7 @@ import { MutationsOverTime, type MutationsOverTimeProps } from './mutations-over
 import { LAPIS_URL } from '../../constants';
 import referenceGenome from '../../lapisApi/__mockData__/referenceGenome.json';
 import { LapisUrlContextProvider } from '../LapisUrlContext';
+import { MutationAnnotationsContextProvider } from '../MutationAnnotationsContext';
 import { ReferenceGenomeContext } from '../ReferenceGenomeContext';
 import { expectInvalidAttributesErrorMessage } from '../shared/stories/expectErrorMessage';
 
@@ -38,13 +39,32 @@ const meta: Meta<MutationsOverTimeProps> = {
 
 export default meta;
 
+const mutationAnnotations = [
+    {
+        name: 'I am a mutation annotation!',
+        description: 'This describes what is special about these mutations.',
+        symbol: '#',
+        nucleotideMutations: ['C44T', 'C774T', 'G24872T', 'T23011-'],
+        aminoAcidMutations: ['S:501Y', 'S:S31-', 'ORF1a:S4286C'],
+    },
+    {
+        name: 'I am another mutation annotation!',
+        description: 'This describes what is special about these other mutations.',
+        symbol: '+',
+        nucleotideMutations: ['C44T', 'A13121T'],
+        aminoAcidMutations: ['S:501Y', 'S:S31-', 'ORF1a:S4286C'],
+    },
+];
+
 export const Default: StoryObj<MutationsOverTimeProps> = {
     render: (args: MutationsOverTimeProps) => (
-        <LapisUrlContextProvider value={LAPIS_URL}>
-            <ReferenceGenomeContext.Provider value={referenceGenome}>
-                <MutationsOverTime {...args} />
-            </ReferenceGenomeContext.Provider>
-        </LapisUrlContextProvider>
+        <MutationAnnotationsContextProvider value={mutationAnnotations}>
+            <LapisUrlContextProvider value={LAPIS_URL}>
+                <ReferenceGenomeContext.Provider value={referenceGenome}>
+                    <MutationsOverTime {...args} />
+                </ReferenceGenomeContext.Provider>
+            </LapisUrlContextProvider>
+        </MutationAnnotationsContextProvider>
     ),
     args: {
         lapisFilter: { pangoLineage: 'JN.1*', dateFrom: '2024-01-15', dateTo: '2024-07-10' },
@@ -55,6 +75,15 @@ export const Default: StoryObj<MutationsOverTimeProps> = {
         lapisDateField: 'date',
         initialMeanProportionInterval: { min: 0.05, max: 0.9 },
     },
+    play: async ({ canvas }) => {
+        await waitFor(async () => {
+            const annotatedMutation = canvas.getAllByText('C44T')[0];
+            await expect(annotatedMutation).toBeVisible();
+            await userEvent.click(annotatedMutation);
+        });
+
+        await waitFor(() => expect(canvas.getByText('Annotations for C44T')).toBeVisible());
+    },
 };
 
 // This test uses mock data: showMessagWhenTooManyMutations.ts (through mutationOverTimeWorker.mock.ts)

package/src/preact/mutationsOverTime/mutations-over-time.tsx

@@ -161,7 +161,13 @@ const MutationsOverTimeTabs: FunctionComponent<MutationOverTimeTabsProps> = ({
             case 'grid':
                 return {
                     title: 'Grid',
-                    content: <MutationsOverTimeGrid data={filteredData} colorScale={colorScale} />,
+                    content: (
+                        <MutationsOverTimeGrid
+                            data={filteredData}
+                            colorScale={colorScale}
+                            sequenceType={originalComponentProps.sequenceType}
+                        />
+                    ),
                 };
         }
     };
@@ -257,6 +263,12 @@ const MutationsOverTimeInfo: FunctionComponent<MutationsOverTimeInfoProps> = ({
                 organism has multiple segments/genes), and applying a filter based on the proportion of the mutation's
                 occurrence over the entire time range.
             </InfoParagraph>
+            <InfoParagraph>
+                The grid cells have a tooltip that will show more detailed information. It shows the count of samples
+                that have the mutation and the count of samples with coverage (i.e. a non-ambiguous read) in this
+                timeframe. Ambiguous reads are excluded when calculating the proportion. It also shows the total count
+                of samples in this timeframe.
+            </InfoParagraph>
             <InfoComponentCode componentName='mutations-over-time' params={originalComponentProps} lapisUrl={lapis} />
         </Info>
     );

package/src/preact/sequencesByLocation/sequences-by-location-map.tsx

@@ -5,7 +5,7 @@ import { useEffect, useRef } from 'preact/hooks';
 
 import type { EnhancedGeoJsonFeatureProperties } from '../../query/computeMapLocationData';
 import { InfoHeadline1, InfoParagraph } from '../components/info';
-import { Modal, useModalRef } from '../components/modal';
+import { Modal } from '../components/modal';
 import { AspectRatio } from '../shared/aspectRatio/AspectRatio';
 import { formatProportion } from '../shared/table/formatProportion';
 
@@ -102,39 +102,37 @@ const DataMatchInformation: FunctionComponent<DataMatchInformationProps> = ({
     nullCount,
     hasTableView,
 }) => {
-    const modalRef = useModalRef();
-
     const proportion = formatProportion(countOfMatchedLocationData / totalCount);
 
     return (
-        <>
-            <button
-                onClick={() => modalRef.current?.showModal()}
-                className='text-sm absolute bottom-0 px-1 z-[1001] bg-white rounded border cursor-pointer tooltip'
-                data-tip='Click for detailed information'
-            >
+        <Modal
+            buttonClassName='text-sm absolute bottom-0 px-1 z-[1001] bg-white rounded border'
+            modalContent={
+                <>
+                    <InfoHeadline1>Sequences By Location - Map View</InfoHeadline1>
+                    <InfoParagraph>
+                        The current filter has matched {totalCount.toLocaleString('en-us')} sequences. From these
+                        sequences, we were able to match {countOfMatchedLocationData.toLocaleString('en-us')} (
+                        {proportion}) on locations on the map.
+                    </InfoParagraph>
+                    <InfoParagraph>
+                        {unmatchedLocations.length > 0 && (
+                            <>
+                                The following locations from the data could not be matched on the map:{' '}
+                                {unmatchedLocations.map((it) => `"${it}"`).join(', ')}.{' '}
+                            </>
+                        )}
+                        {nullCount > 0 &&
+                            `${nullCount.toLocaleString('en-us')} matching sequences have no location information. `}
+                        {hasTableView && 'You can check the table view for more detailed information.'}
+                    </InfoParagraph>
+                </>
+            }
+        >
+            <p className='tooltip' data-tip='Click for detailed information'>
                 This map shows {proportion} of the data.
-            </button>
-            <Modal modalRef={modalRef}>
-                <InfoHeadline1>Sequences By Location - Map View</InfoHeadline1>
-                <InfoParagraph>
-                    The current filter has matched {totalCount.toLocaleString('en-us')} sequences. From these sequences,
-                    we were able to match {countOfMatchedLocationData.toLocaleString('en-us')} ({proportion}) on
-                    locations on the map.
-                </InfoParagraph>
-                <InfoParagraph>
-                    {unmatchedLocations.length > 0 && (
-                        <>
-                            The following locations from the data could not be matched on the map:{' '}
-                            {unmatchedLocations.map((it) => `"${it}"`).join(', ')}.{' '}
-                        </>
-                    )}
-                    {nullCount > 0 &&
-                        `${nullCount.toLocaleString('en-us')} matching sequences have no location information. `}
-                    {hasTableView && 'You can check the table view for more detailed information.'}
-                </InfoParagraph>
-            </Modal>
-        </>
+            </p>
+        </Modal>
     );
 };
 

package/src/preact/wastewater/mutationsOverTime/wastewater-mutations-over-time.tsx

@@ -102,7 +102,12 @@ const MutationsOverTimeTabs: FunctionComponent<MutationOverTimeTabsProps> = ({
     const tabs = mutationOverTimeDataPerLocation.map(({ location, data }) => ({
         title: location,
         content: (
-            <MutationsOverTimeGrid data={data} colorScale={colorScale} maxNumberOfGridRows={maxNumberOfGridRows} />
+            <MutationsOverTimeGrid
+                data={data}
+                colorScale={colorScale}
+                maxNumberOfGridRows={maxNumberOfGridRows}
+                sequenceType={originalComponentProps.sequenceType}
+            />
         ),
     }));
 

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

@@ -0,0 +1,10 @@
+import { describe, expectTypeOf, test } from 'vitest';
+
+import { AppComponent } from './gs-app';
+import { type MutationAnnotations } from './mutation-annotations-context';
+
+describe('gs-app types', () => {
+    test('mutationAnnotations type should match', ({}) => {
+        expectTypeOf(AppComponent.prototype).toHaveProperty('mutationAnnotations').toEqualTypeOf<MutationAnnotations>();
+    });
+});

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

@@ -10,6 +10,7 @@ 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 MutationAnnotations, mutationAnnotationsContext } from './mutation-annotations-context';
 import type { ReferenceGenome } from '../lapisApi/ReferenceGenome';
 import referenceGenome from '../lapisApi/__mockData__/referenceGenome.json';
 
@@ -34,18 +35,29 @@ const meta: Meta = {
 
 export default meta;
 
-const Template: StoryObj<{ lapis: string }> = {
+type StoryProps = { lapis: string; mutationAnnotations: MutationAnnotations };
+
+const Template: StoryObj<StoryProps> = {
     render: (args) => {
-        return html` <gs-app lapis="${args.lapis}">
+        return html` <gs-app lapis="${args.lapis}" .mutationAnnotations="${args.mutationAnnotations}">
             <gs-app-display></gs-app-display>
         </gs-app>`;
     },
     args: {
         lapis: LAPIS_URL,
+        mutationAnnotations: [
+            {
+                name: 'I am an annotation!',
+                description: 'This describes what is special about these mutations.',
+                symbol: '*',
+                nucleotideMutations: ['C44T', 'C774T', 'G24872T', 'T23011-'],
+                aminoAcidMutations: ['S:501Y', 'S:S31-', 'ORF1a:S4286C'],
+            },
+        ],
     },
 };
 
-export const Default: StoryObj<{ lapis: string }> = {
+export const Default: StoryObj<StoryProps> = {
     ...Template,
     play: async ({ canvasElement }) => {
         const canvas = within(canvasElement);
@@ -53,11 +65,12 @@ export const Default: StoryObj<{ lapis: string }> = {
         await waitFor(async () => {
             await expect(canvas.getByText(LAPIS_URL)).toBeVisible();
             await expect(canvas.getByText('"name": "ORF1a",', { exact: false })).toBeVisible();
+            await expect(canvas.getByText('I am an annotation!', { exact: false })).toBeVisible();
         });
     },
 };
 
-export const WithNoLapisUrl: StoryObj<{ lapis: string }> = {
+export const WithNoLapisUrl: StoryObj<StoryProps> = {
     ...Default,
     args: {
         ...Default.args,
@@ -72,7 +85,7 @@ export const WithNoLapisUrl: StoryObj<{ lapis: string }> = {
     },
 };
 
-export const DelayFetchingReferenceGenome: StoryObj<{ lapis: string }> = {
+export const DelayFetchingReferenceGenome: StoryObj<StoryProps> = {
     ...Template,
     parameters: {
         fetchMock: {
@@ -95,7 +108,7 @@ export const DelayFetchingReferenceGenome: StoryObj<{ lapis: string }> = {
     },
 };
 
-export const FailsToFetchReferenceGenome: StoryObj<{ lapis: string }> = {
+export const FailsToFetchReferenceGenome: StoryObj<StoryProps> = {
     ...Template,
     args: {
         lapis: 'https://url.to.lapis-definitely-not-a-valid-url',
@@ -121,6 +134,9 @@ class AppDisplay extends LitElement {
         genes: [],
     };
 
+    @consume({ context: mutationAnnotationsContext, subscribe: true })
+    mutationAnnotations: MutationAnnotations = [];
+
     override render() {
         return html`
             <h1 class="text-xl font-bold">Dummy component</h1>
@@ -132,6 +148,8 @@ class AppDisplay extends LitElement {
             <p>${this.lapis}</p>
             <h2 class="text-lg font-bold">Reference genomes</h2>
             <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>
         `;
     }
 

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

@@ -6,6 +6,7 @@ import type { DetailedHTMLProps, HTMLAttributes } from 'react';
 import z from 'zod';
 
 import { lapisContext } from './lapis-context';
+import { mutationAnnotationsContext } from './mutation-annotations-context';
 import { referenceGenomeContext } from './reference-genome-context';
 import { type ReferenceGenome } from '../lapisApi/ReferenceGenome';
 import { fetchReferenceGenome } from '../lapisApi/lapisApi';
@@ -21,6 +22,7 @@ const lapisUrlSchema = z.string().url();
  * 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
+ * - distribute the mutation annotations config to its children
  *
  * This will show an error message if the reference genome cannot be fetched
  * (e.g., due to an invalid LAPIS URL).
@@ -40,6 +42,21 @@ export class AppComponent extends LitElement {
     @property()
     lapis: string = '';
 
+    /**
+     * Supply lists of mutations that are especially relevant for the current organism.
+     * Whenever other components display mutations, matching mutations will be highlighted by appending the `symbol`.
+     * On hover, a tooltip with the `name` and `description` will be shown.
+     */
+    @provide({ context: mutationAnnotationsContext })
+    @property({ type: Array })
+    mutationAnnotations: {
+        name: string;
+        description: string;
+        symbol: string;
+        nucleotideMutations: string[];
+        aminoAcidMutations: string[];
+    }[] = [];
+
     /**
      * @internal
      */

package/src/web-components/mutation-annotations-context.ts

@@ -0,0 +1,16 @@
+import { createContext } from '@lit/context';
+import z from 'zod';
+
+const mutationAnnotationSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    symbol: z.string(),
+    nucleotideMutations: z.array(z.string()),
+    aminoAcidMutations: z.array(z.string()),
+});
+export type MutationAnnotation = z.infer<typeof mutationAnnotationSchema>;
+
+export const mutationAnnotationsSchema = z.array(mutationAnnotationSchema);
+export type MutationAnnotations = z.infer<typeof mutationAnnotationsSchema>;
+
+export const mutationAnnotationsContext = createContext<MutationAnnotations>(Symbol('mutation-annotations-context'));

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

@@ -64,9 +64,26 @@ const meta: Meta<Required<MutationsOverTimeProps>> = {
 
 export default meta;
 
+const mutationAnnotations = [
+    {
+        name: 'I am a mutation annotation!',
+        description: 'This describes what is special about these mutations.',
+        symbol: '#',
+        nucleotideMutations: ['C44T', 'C774T', 'G24872T', 'T23011-'],
+        aminoAcidMutations: ['S:501Y', 'S:S31-', 'ORF1a:S4286C'],
+    },
+    {
+        name: 'I am another mutation annotation!',
+        description: 'This describes what is special about these other mutations.',
+        symbol: '+',
+        nucleotideMutations: ['C44T', 'A13121T'],
+        aminoAcidMutations: ['S:501Y', 'S:S31-', 'ORF1a:S4286C'],
+    },
+];
+
 const Template: StoryObj<Required<MutationsOverTimeProps>> = {
     render: (args) => html`
-        <gs-app lapis="${LAPIS_URL}">
+        <gs-app lapis="${LAPIS_URL}" .mutationAnnotations=${mutationAnnotations}>
             <gs-mutations-over-time
                 .lapisFilter=${args.lapisFilter}
                 .sequenceType=${args.sequenceType}